feat: add backlog-bridge-adapter logic for github initially (#108)

* feat: add GitHub issue state management and branch tracking for applied changes

- Fix issue title extraction for archived proposals
- Add automatic issue closure for applied/deprecated/discarded proposals
- Add state_reason mapping (completed/not_planned) based on proposal status
- Add comments when issues are created/closed with status explanations
- Add branch information to comments for applied changes
- Update issue state even when content hash hasn't changed
- Support GitHub issue close reasons (completed, not_planned, duplicate)

* feat: add --include-archived flag and improve branch detection

- Add --include-archived flag to sync bridge command for updating archived change proposals
- Improve branch detection algorithm with change_id-based prioritization
- Add flexible matching (exact substring + key words) for better branch identification
- Always update comments for applied status when --include-archived is set
- Update documentation with new parameter and examples
- Update CHANGELOG.md with new features

This allows retroactively updating existing GitHub issues with improved comment logic
and branch detection algorithms, even for archived change proposals.

* Fix failed tests

* Apply review fixes

* Fix specmatic tests

---------

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

Author: djm81

CHANGELOG.md

@@ -9,6 +9,75 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.25.0] - 2026-01-15
+
+### Added (0.25.0)
+
+- **Archived Change Proposal Sync**: New `--include-archived` flag for `sync bridge` command
+  - **Purpose**: Include archived change proposals in sync to update existing GitHub issues with new comment logic and branch detection improvements
+  - **Use Case**: When you improve comment formatting or branch detection algorithms, update historical issues retroactively
+  - **Behavior**: When `--include-archived` is set with `--update-existing`, archived proposals are included and comments are always updated for applied status
+  - **Example**: `specfact sync bridge --adapter github --mode export-only --include-archived --update-existing`
+  - **Documentation**: See `docs/guides/devops-adapter-integration.md#updating-archived-change-proposals`
+
+- **Improved Branch Detection**: Enhanced branch detection algorithm for GitHub issue comments
+  - **Prioritization**: Branches matching the change_id in their name are now prioritized
+  - **Flexible Matching**: Uses both exact substring matching and key words matching (e.g., "change" and "tracking" from "add-code-change-tracking")
+  - **Accuracy**: Correctly identifies implementation branches even when multiple branches contain the same commits
+  - **Use Case**: Ensures GitHub issue comments show the correct implementation branch for applied changes
+
+- **Backlog Adapter Import Capability**: GitHub adapter now supports importing GitHub Issues as OpenSpec change proposals
+  - **New Method**: `import_artifact("github_issue", issue_data, project_bundle, bridge_config)` in `GitHubAdapter`
+  - **Parsing**: Parses GitHub issue body/markdown to extract change proposal data (Why, What Changes sections)
+  - **Status Mapping**: Maps GitHub labels to OpenSpec change status (tool-agnostic pattern)
+  - **Metadata Storage**: Stores GitHub issue metadata in `source_tracking` (tool-agnostic pattern)
+  - **Extensibility**: Reusable patterns for future backlog adapters (ADO, Jira, Linear)
+  - **Documentation**: See `docs/adapters/github.md` and `docs/adapters/backlog-adapter-patterns.md`
+
+- **Bidirectional Status Synchronization**: GitHub adapter now supports bidirectional status sync
+  - **New Methods**: `sync_status_to_github()` and `sync_status_from_github()` in `GitHubAdapter`
+  - **Conflict Resolution**: Three strategies: `prefer_openspec`, `prefer_backlog`, `merge` (most advanced)
+  - **Label Updates**: Automatically updates GitHub issue labels based on OpenSpec change status
+  - **Status Mapping**: Tool-agnostic status mapping interface for future backlog adapters
+  - **Documentation**: See `docs/adapters/github.md` for usage examples
+
+- **Backlog Adapter Extensibility Pattern**: Reusable base class for implementing backlog adapters
+  - **New Module**: `src/specfact_cli/adapters/backlog_base.py` with `BacklogAdapterMixin`
+  - **Abstract Methods**: Tool-agnostic interfaces for status mapping and metadata extraction
+  - **Reusable Utilities**: Conflict resolution, source tracking creation, import workflow
+  - **Documentation**: See `docs/adapters/backlog-adapter-patterns.md` for implementation guide
+  - **Future Adapters**: Patterns documented for ADO, Jira, Linear implementations
+
+- **Validation Integration with Change Proposals**: SpecFact validation now integrates with OpenSpec change proposals
+  - **New Module**: `src/specfact_cli/validators/change_proposal_integration.py`
+  - **Change Proposal Loading**: `load_active_change_proposals()` loads active proposals (proposed/in-progress)
+  - **Spec Merging**: `merge_specs_with_change_proposals()` merges current Spec-Kit specs with proposed OpenSpec changes
+  - **Status Updates**: `update_validation_status()` updates validation status in change proposals
+  - **Result Reporting**: `report_validation_results_to_backlog()` reports validation results to GitHub Issues
+  - **Conflict Detection**: Detects and reports conflicts when same requirement modified in multiple proposals
+  - **Cross-Repo Support**: Supports external OpenSpec repositories via `bridge_config.external_base_path`
+  - **Documentation**: See `docs/validation-integration.md` for complete integration guide
+
+- **Integration Test Suite**: Comprehensive integration tests for adapter workflows
+  - **Backlog Sync Tests**: `tests/integration/sync/test_backlog_sync.py` - Bidirectional backlog sync (GitHub)
+  - **Validation Integration Tests**: `tests/integration/specfact_cli/validators/test_change_proposal_validation.py` - Validation with change proposals
+  - **Test Patterns**: Reusable test patterns for future backlog adapters (ADO, Jira, Linear)
+  - **Coverage**: Tests cover export, import, status sync, conflict resolution, and validation integration
+
+### Changed (0.25.0)
+
+- **GitHub Adapter Capabilities**: Updated `get_capabilities()` to reflect bidirectional sync support
+  - **Before**: `supported_sync_modes=["export-only"]`
+  - **After**: `supported_sync_modes=["bidirectional"]`
+  - **Impact**: Adapter now supports both export and import operations
+
+### Documentation (0.25.0)
+
+- **New Documentation**: `docs/validation-integration.md` - Complete guide for validation integration with change proposals
+- **New Documentation**: `docs/adapters/backlog-adapter-patterns.md` - Patterns for implementing future backlog adapters
+- **New Documentation**: `docs/adapters/github.md` - GitHub adapter reference with usage examples
+- **Updated Documentation**: Adapter documentation updated with import capability and bidirectional sync
+
 ## [0.24.1] - 2026-01-12
 
 ### Fixed (0.24.1)

docs/README.md

@@ -16,7 +16,10 @@ SpecFact isn't just a technical tool—it's designed for **real-world agile/scru
 
 **Each role works in their own Markdown files** (no YAML editing), and SpecFact syncs everything together automatically. Perfect for teams using agile/scrum practices with clear role separation.
 
-👉 **[Agile/Scrum Workflows Guide](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Complete guide to persona-based team collaboration
+**🆕 NEW: DevOps Backlog Integration** - SpecFact now integrates directly into your agile DevOps workflows! Bidirectionally sync OpenSpec change proposals with GitHub Issues, track implementation progress automatically, and keep your backlog in sync with your specifications.
+
+👉 **[Agile/Scrum Workflows Guide](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Complete guide to persona-based team collaboration  
+👉 **[DevOps Backlog Integration](guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows
 
 ---
 
@@ -32,7 +35,7 @@ SpecFact isn't just a technical tool—it's designed for **real-world agile/scru
 - ✅ **Brownfield-first** → Spec-Kit/OpenSpec excel at new features; SpecFact understands existing code
 - ✅ **Formal verification** → Spec-Kit/OpenSpec use LLM suggestions; SpecFact uses mathematical proof (CrossHair)
 - ✅ **Team collaboration** → Spec-Kit is single-user focused; SpecFact supports persona-based workflows for agile teams
-- ✅ **DevOps integration** → Bridge adapters sync change proposals to GitHub Issues, ADO, Linear, Jira
+- ✅ **DevOps integration** 🆕 → **Bidirectional backlog sync** - Sync change proposals to GitHub Issues (and future: ADO, Linear, Jira) with automatic progress tracking
 - ✅ **GitHub Actions integration** → Works seamlessly with your existing GitHub workflows
 
 **Perfect together:**
@@ -93,14 +96,15 @@ specfact enforce sdd --bundle my-project
 
 ### Working with an Agile/Scrum Team?
 
-**Primary Goal**: Enable team collaboration with role-based workflows
+**Primary Goal**: Enable team collaboration with role-based workflows and DevOps integration
 
 1. **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** ⭐ **START HERE** - Persona-based team collaboration
-2. **[Command Reference - Project Commands](reference/commands.md#project---project-bundle-management)** - `project export` and `project import` commands
-3. **[Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows)** - How Product Owners, Architects, and Developers work together
-4. **[Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor)** - DoR validation and sprint planning
+2. **[DevOps Backlog Integration](guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into your agile DevOps workflows with bidirectional GitHub Issues sync
+3. **[Command Reference - Project Commands](reference/commands.md#project---project-bundle-management)** - `project export` and `project import` commands
+4. **[Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows)** - How Product Owners, Architects, and Developers work together
+5. **[Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor)** - DoR validation and sprint planning
 
-**Time**: 15-30 minutes | **Result**: Understanding how your team can collaborate with SpecFact
+**Time**: 15-30 minutes | **Result**: Understanding how your team can collaborate with SpecFact and integrate with your DevOps backlog
 
 ---
 
@@ -178,8 +182,8 @@ specfact enforce sdd --bundle my-project
 
 - [Spec-Kit Journey](guides/speckit-journey.md) - Add enforcement to Spec-Kit projects
 - [Spec-Kit Comparison](guides/speckit-comparison.md) - Understand when to use each tool
-- [OpenSpec Journey](guides/openspec-journey.md) 🆕 - OpenSpec integration with SpecFact (DevOps export ✅, bridge adapter ⏳)
-- [DevOps Adapter Integration](guides/devops-adapter-integration.md) - GitHub Issues, backlog tracking, and progress comments
+- [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
 - [Bridge Adapters](reference/commands.md#sync-bridge) - OpenSpec and DevOps integration
 
 #### Team Collaboration & Agile/Scrum