nold-ai · djm81 · Feb 12, 2026 · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,23 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.30.3] - 2026-02-12
+
+### Fixed (0.30.3)
+
+- **Backlog refine writeback parsing for ADO/GitHub**
+  - `specfact backlog refine --write` now parses structured refinement output (markdown headings and label-style fields like `Description:`, `Acceptance Criteria:`, `Story Points:`, `Business Value:`, `Priority:`) into canonical fields before adapter writeback.
+  - ADO writeback now avoids writing labeled refinement blocks verbatim into description and instead updates mapped fields with split canonical values.
+  - GitHub writeback now preserves canonical field updates even when refined bodies include structured headings that do not explicitly include all core field sections.
+- **Refine command maintainability**
+  - Decomposed `backlog refine` orchestration into focused helper methods (stdin refinement capture, update-field construction, writeback, optional OpenSpec comment) to reduce top-level command complexity while keeping behavior parity.
+
+### Changed (0.30.3)
+
+- **Version**: Bumped to `0.30.3` (patch).
+
+---
+
 ## [0.30.2] - 2026-02-11
 
 ### Fixed (0.30.2)

diff --git a/docs/guides/backlog-refinement.md b/docs/guides/backlog-refinement.md
@@ -260,6 +260,10 @@ This helps copilot identify missing elements that need to be added during refine
 - Records `refinement_timestamp`
 - Updates template detection metadata
 - **Preserves all other fields** (assignees, tags, state, priority, due_date, story_points, etc.)
+- Parses structured refinement output into canonical fields before writeback:
+  - accepts markdown-heading sections and label-style sections (for example `Description:`, `Acceptance Criteria:`, `Story Points:`)
+  - maps ADO description/acceptance criteria/metrics to separate provider fields
+  - avoids writing prompt label blocks verbatim into ADO description
 
 **Field Preservation Policy**:
 

diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -3697,6 +3697,10 @@ specfact backlog refine <ADAPTER> [OPTIONS]
 
 - `--preview` / `--no-preview` - Preview mode: show what will be written without updating backlog (default: `--preview`)
 - `--write` - Write mode: explicitly opt-in to update remote backlog (requires `--write` flag)
+- During `--write`, structured refinement output is parsed into canonical fields before adapter updates.
+  - Supports markdown headings and label-style sections (for example `Description:`, `Acceptance Criteria:`, `Story Points:`).
+  - ADO updates mapped fields separately (description, acceptance criteria, metrics) instead of writing label blocks verbatim to description.
+  - GitHub keeps field updates consistent even when refined body contains headings that omit some core field sections.
 
 **Definition of Ready (DoR):**
 

diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md
@@ -60,6 +60,7 @@ All entries in the table below are pending implementation.
 |--------|-------|---------------|----------|------------|
 | backlog-core | 01 | backlog-core-01-dependency-analysis-commands | [#116](https://github.com/nold-ai/specfact-cli/issues/116) | — |
 | backlog-core | 02 | backlog-core-02-interactive-issue-creation | [#173](https://github.com/nold-ai/specfact-cli/issues/173) | #116 (optional: #176, #177) |
+| backlog-core | 03 | backlog-core-03-refine-writeback-field-splitting | #225 | — |
 
 ### backlog-scrum
 

diff --git a/...c/changes/backlog-core-03-refine-writeback-field-splitting/CHANGE_VALIDATION.md b/...c/changes/backlog-core-03-refine-writeback-field-splitting/CHANGE_VALIDATION.md
@@ -0,0 +1,78 @@
+# Change Validation Report: backlog-core-03-refine-writeback-field-splitting
+
+**Validation Date**: 2026-02-11T14:31:00+01:00
+**Change Proposal**: [proposal.md](./proposal.md)
+**Validation Method**: Local static dependency scan + OpenSpec strict validation
+
+## Executive Summary
+
+- Breaking Changes: 0 detected
+- Dependent Files Reviewed: 4
+- Impact Level: Low
+- Validation Result: Pass
+- User Decision: Proceed with implementation
+
+## Dependency and Interface Analysis
+
+Reviewed writeback path and parser touch points:
+
+- `src/specfact_cli/modules/backlog/src/commands.py`
+- `src/specfact_cli/adapters/ado.py`
+- `src/specfact_cli/adapters/github.py`
+- `tests/unit/commands/test_backlog_commands.py`
+- `tests/unit/adapters/test_github_backlog_adapter.py`
+
+No public CLI signature changes or adapter method signature changes were introduced by this change.
+
+## Impact Assessment
+
+- **Code Impact**: Refinement write path now parses structured response content before writeback.
+- **Test Impact**: Added regression coverage for label-style parsing and GitHub fallback behavior.
+- **Documentation Impact**: Potential wording updates for refine writeback behavior (tasked in `tasks.md`).
+- **Release Impact**: Patch-level bugfix.
+
+## Format Validation
+
+- **proposal.md Format**: Pass
+- **tasks.md Format**: Pass
+- **spec delta Format**: Pass (Given/When/Then scenarios)
+- **Config.yaml Compliance**: Pass
+
+## OpenSpec Validation
+
+- **Status**: Pass
+- **Validation Command**: `openspec validate backlog-core-03-refine-writeback-field-splitting --strict`
+- **Result**: `Change 'backlog-core-03-refine-writeback-field-splitting' is valid`
+- **Notes**: Non-blocking telemetry network errors from PostHog occurred after validation in restricted network environment.
+
+## Refactor Follow-up Validation (2026-02-11)
+
+- `hatch run type-check`: Pass (`0 errors`) after decomposing `refine` command helper flow.
+- `hatch test -- tests/unit/commands/test_backlog_commands.py tests/unit/adapters/test_github_backlog_adapter.py tests/unit/adapters/test_ado_backlog_adapter.py -v`: Pass (`64 passed`).
+- `hatch run format`: Pass.
+
+## Review Follow-up Validation (2026-02-12)
+
+- `openspec validate backlog-core-03-refine-writeback-field-splitting --strict`: Pass.
+- `hatch test -- tests/unit/commands/test_backlog_commands.py -k TestParseRefinementOutputFields -v`: Pass (`3 passed`).
+- `hatch test -- tests/unit/adapters/test_ado_backlog_adapter.py tests/unit/adapters/test_github_backlog_adapter.py -v`: Pass (`35 passed`).
+- `hatch run type-check`: Pass (`0 errors`, warnings unchanged).
+- `hatch run format`: Pass.
+
+## Review Follow-up Validation (Case-Insensitive Heading Match, 2026-02-12)
+
+- `hatch test -- tests/unit/commands/test_backlog_commands.py -k uppercase_heading_style_notes_and_dependencies -v`: Failing pre-implementation evidence captured.
+- `hatch test -- tests/unit/commands/test_backlog_commands.py -k TestParseRefinementOutputFields -v`: Pass (`4 passed`) after parser fix.
+- `hatch test -- tests/unit/adapters/test_ado_backlog_adapter.py tests/unit/adapters/test_github_backlog_adapter.py -v`: Pass (`35 passed`).
+
+## Review Follow-up Validation (Label-Only Description Fallback, 2026-02-12)
+
+- `hatch test -- tests/unit/commands/test_backlog_commands.py -k label_only_output_without_description -v`: Failing pre-implementation evidence captured.
+- `hatch test -- tests/unit/commands/test_backlog_commands.py -k TestParseRefinementOutputFields -v`: Pass (`5 passed`) after parser fix.
+- `hatch test -- tests/unit/adapters/test_ado_backlog_adapter.py tests/unit/adapters/test_github_backlog_adapter.py -v`: Pass (`35 passed`).
+
+## Next Steps
+
+1. Complete implementation and tests per `tasks.md`.
+2. Run quality gates.
+3. Update version/changelog and docs if needed.
diff --git a/openspec/changes/backlog-core-03-refine-writeback-field-splitting/TDD_EVIDENCE.md b/openspec/changes/backlog-core-03-refine-writeback-field-splitting/TDD_EVIDENCE.md
@@ -0,0 +1,82 @@
+# TDD Evidence: backlog-core-03-refine-writeback-field-splitting
+
+## Pre-Implementation Failing Run
+
+- **Timestamp**: 2026-02-11T14:30:38+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k parse_refinement_output_fields -v`
+- **Result**: Failed (collection error)
+- **Failure Summary**:
+  - `ImportError: cannot import name '_parse_refinement_output_fields'`
+  - New parser behavior is specified in tests but not implemented yet.
+
+## Post-Implementation Passing Run
+
+- **Timestamp**: 2026-02-11T14:32:52+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py tests/unit/adapters/test_github_backlog_adapter.py -v`
+- **Result**: Passed
+- **Summary**:
+  - `41 passed`
+  - Includes regression coverage for:
+    - label-style refinement field parsing
+    - markdown heading refinement parsing
+    - GitHub writeback fallback when structured body lacks core field headings.
+
+## Review Follow-up: Heading-Style Narrative Regression
+
+### Pre-Implementation Failing Run
+
+- **Timestamp**: 2026-02-12T10:22:00+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k heading_style_notes_and_dependencies -v`
+- **Result**: Failed
+- **Failure Summary**:
+  - `test_preserves_heading_style_notes_and_dependencies_in_body_markdown` failed.
+  - Parsed `body_markdown` contained only description (`User-facing summary.`) and dropped heading-style `## Notes` section.
+
+### Post-Implementation Passing Run
+
+- **Timestamp**: 2026-02-12T10:24:00+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k TestParseRefinementOutputFields -v`
+- **Result**: Passed
+- **Summary**:
+  - `3 passed`
+  - Includes heading-style preservation regression test for `## Notes` and `## Dependencies`.
+
+## Review Follow-up: Case-Insensitive Heading Matching
+
+### Pre-Implementation Failing Run
+
+- **Timestamp**: 2026-02-12T10:42:00+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k uppercase_heading_style_notes_and_dependencies -v`
+- **Result**: Failed
+- **Failure Summary**:
+  - `test_preserves_uppercase_heading_style_notes_and_dependencies_in_body_markdown` failed.
+  - Parsed `body_markdown` contained only description and dropped uppercase `## NOTES` / `## DEPENDENCIES` narrative sections.
+
+### Post-Implementation Passing Run
+
+- **Timestamp**: 2026-02-12T10:43:00+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k TestParseRefinementOutputFields -v`
+- **Result**: Passed
+- **Summary**:
+  - `4 passed`
+  - Includes uppercase heading regression coverage for `## NOTES` and `## DEPENDENCIES`.
+
+## Review Follow-up: Label-Only Output Without Description
+
+### Pre-Implementation Failing Run
+
+- **Timestamp**: 2026-02-12T10:49:00+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k label_only_output_without_description -v`
+- **Result**: Failed
+- **Failure Summary**:
+  - `test_label_only_output_without_description_does_not_fallback_to_raw_payload` failed.
+  - Parser retained the full raw label payload as fallback `description` and `body_markdown` when no `Description:` block existed.
+
+### Post-Implementation Passing Run
+
+- **Timestamp**: 2026-02-12T10:50:00+01:00
+- **Command**: `hatch test -- tests/unit/commands/test_backlog_commands.py -k TestParseRefinementOutputFields -v`
+- **Result**: Passed
+- **Summary**:
+  - `5 passed`
+  - Includes regression coverage for label-only field blocks without `Description:`.
diff --git a/openspec/changes/backlog-core-03-refine-writeback-field-splitting/proposal.md b/openspec/changes/backlog-core-03-refine-writeback-field-splitting/proposal.md
@@ -0,0 +1,30 @@
+# Change: Backlog Refine Writeback Field Splitting for ADO/GitHub
+
+## Why
+
+
+`specfact backlog refine --write` currently applies the raw copilot response as `body_markdown` and does not parse structured refinement output back into canonical fields before adapter writeback. For Azure DevOps this causes `System.Description` to receive a verbatim payload containing labels like `Description`, `Acceptance Criteria`, `Story Points`, `Business Value`, `Priority`, `Area Path`, and provider markers instead of updating separate fields. GitHub can exhibit the same issue when copilot output uses label-style sections instead of markdown headings.
+
+This breaks the provider-aware contract implied by refinement prompts and produces low-quality remote item updates.
+
+## What Changes
+
+
+- **MODIFY**: Backlog refine write path to parse structured refinement content into canonical fields (`description`, `acceptance_criteria`, `story_points`, `business_value`, `priority`, `work_item_type`) before writeback.
+- **MODIFY**: Normalize label-style refinement output to canonical markdown sections so both ADO and GitHub writeback paths behave deterministically.
+- **MODIFY**: ADO/GitHub writeback behavior to prefer parsed refined values over stale pre-refinement values when `--write` is used.
+- **MODIFY**: Refactor `backlog refine` orchestration in `commands.py` into smaller helper methods (initialization, export/import handling, writeback/comment flow) to reduce command-function complexity and improve readability.
+- **ADD**: Regression tests for ADO and GitHub writeback from label-style refinement output.
+
+## Capabilities
+- **backlog-refinement**: Provider-aware parsing and canonical field splitting for `specfact backlog refine --write`.
+
+---
+
+## Source Tracking
+
+<!-- source_repo: nold-ai/specfact-cli -->
+- **GitHub Issue**: #225
+- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/225>
+- **Last Synced Status**: proposed
+- **Sanitized**: false
diff --git a/...cklog-core-03-refine-writeback-field-splitting/specs/backlog-refinement/spec.md b/...cklog-core-03-refine-writeback-field-splitting/specs/backlog-refinement/spec.md
@@ -0,0 +1,56 @@
+## MODIFIED Requirements
+
+### Requirement: AI Refinement Writeback Preserves Provider Field Semantics
+
+The system SHALL parse structured refinement output into canonical fields before provider writeback so provider-specific fields are updated correctly rather than storing prompt labels verbatim in description/body.
+
+#### Scenario: ADO writeback splits label-style refined output into canonical fields
+
+- **GIVEN** a user runs `specfact backlog refine ado --write`
+- **AND** the refined output uses label-style sections such as `Description:`, `Acceptance Criteria:`, `Story Points:`, `Business Value:`, and `Priority:`
+- **WHEN** the refinement is accepted
+- **THEN** SpecFact parses those sections into canonical fields
+- **AND** writes `description` content to ADO description field
+- **AND** writes `acceptance_criteria`, `story_points`, `business_value`, and `priority` to their mapped ADO fields when present
+- **AND** does not write the entire labeled structure verbatim as ADO description.
+
+#### Scenario: GitHub writeback normalizes label-style refined output to structured markdown
+
+- **GIVEN** a user runs `specfact backlog refine github --write`
+- **AND** the refined output uses label-style sections rather than markdown headings
+- **WHEN** the refinement is accepted
+- **THEN** SpecFact normalizes the output into canonical markdown sections
+- **AND** updates issue body and related canonical fields consistently
+- **AND** avoids duplicating or flattening structured fields into a single unparsed description block.
+
+#### Scenario: Heading-style narrative sections are preserved during writeback parsing
+
+- **GIVEN** a user runs `specfact backlog refine <provider> --write`
+- **AND** the refined output uses markdown headings like `## Notes` and `## Dependencies`
+- **WHEN** the refinement output is parsed into canonical fields for writeback
+- **THEN** `body_markdown` keeps those narrative sections
+- **AND** canonical numeric/provider metadata sections (for example `## Story Points`, `## Business Value`, `## Priority`, `## Provider`) are not duplicated into narrative body text.
+
+#### Scenario: Heading-style narrative sections are matched case-insensitively
+
+- **GIVEN** a user runs `specfact backlog refine <provider> --write`
+- **AND** the refined output uses uppercase narrative headings like `## NOTES` and `## DEPENDENCIES`
+- **WHEN** the refinement output is parsed into canonical fields for writeback
+- **THEN** `body_markdown` preserves those narrative sections as normalized `## Notes` / `## Dependencies` sections
+- **AND** writeback does not silently drop narrative context because of heading case differences.
+
+#### Scenario: Label-only field blocks without Description do not leak raw labels into body/description
+
+- **GIVEN** a user runs `specfact backlog refine <provider> --write`
+- **AND** the refined output contains label-style field blocks (for example `Acceptance Criteria:`, `Story Points:`, `Priority:`) but no `Description:` block
+- **WHEN** the refinement output is parsed into canonical fields for writeback
+- **THEN** canonical fields (for example acceptance criteria and numeric fields) are extracted
+- **AND** parser fallback does not keep the entire raw labeled payload as `description`
+- **AND** `body_markdown` does not contain prompt labels verbatim.
+
+#### Scenario: Refine command orchestration remains behaviorally consistent after decomposition
+
+- **GIVEN** `specfact backlog refine` supports initialization, filtering, export/import, interactive refinement, writeback, and summary flows
+- **WHEN** the command implementation is decomposed into smaller helper methods
+- **THEN** observable CLI behavior and writeback semantics remain unchanged for equivalent inputs
+- **AND** command complexity in the top-level `refine` function is reduced to keep the implementation readable and maintainable.
diff --git a/openspec/changes/backlog-core-03-refine-writeback-field-splitting/tasks.md b/openspec/changes/backlog-core-03-refine-writeback-field-splitting/tasks.md
@@ -0,0 +1,46 @@
+# Tasks: Backlog Refine Writeback Field Splitting for ADO/GitHub
+
+## 1. Git Workflow
+
+- [x] 1.1 Create git branch `bugfix/backlog-refine-writeback-field-splitting` from `dev`
+
+## 2. Spec Deltas
+
+- [x] 2.1 Add/modify `backlog-refinement` spec scenarios for provider-aware writeback field splitting
+- [x] 2.2 Run `openspec validate backlog-core-03-refine-writeback-field-splitting --strict`
+
+## 3. Tests First (TDD)
+
+- [x] 3.1 Add tests for label-style refined output parsing into canonical fields
+- [x] 3.2 Add ADO writeback regression test: structured output does not get written verbatim to description
+- [x] 3.3 Add GitHub writeback regression test for label-style output normalization
+- [x] 3.4 Run targeted tests and capture failing evidence in `openspec/changes/backlog-core-03-refine-writeback-field-splitting/TDD_EVIDENCE.md`
+
+## 4. Implementation
+
+- [x] 4.1 Implement refinement output parser integration in `backlog refine --write` flow
+- [x] 4.2 Ensure parsed canonical fields are applied before adapter update calls
+- [x] 4.3 Add adapter-safe fallback handling for structured label output where needed
+- [x] 4.4 Run targeted tests and capture passing evidence in `openspec/changes/backlog-core-03-refine-writeback-field-splitting/TDD_EVIDENCE.md`
+- [x] 4.5 Refactor `refine` command into smaller helper methods with clear responsibilities
+- [x] 4.6 Keep behavior parity for export/import/write/preview flows after refactor
+- [x] 4.7 Preserve heading-style `## Notes` / `## Dependencies` sections in parsed `body_markdown` for writeback
+- [x] 4.8 Match heading-style `## Notes` / `## Dependencies` sections case-insensitively during parser writeback normalization
+- [x] 4.9 Prevent label-only refinement output (without `Description:`) from leaking raw prompt labels into fallback description/body fields
+
+## 5. Quality Gates
+
+- [x] 5.1 `hatch run format`
+- [x] 5.2 `hatch run type-check`
+- [x] 5.3 `hatch run contract-test`
+- [x] 5.4 `hatch run smart-test`
+
+## 6. Documentation and Release Hygiene
+
+- [x] 6.1 Review and update docs for backlog refine writeback behavior (if needed)
+- [x] 6.2 Bump patch version and sync: `pyproject.toml`, `setup.py`, `src/specfact_cli/__init__.py`
+- [x] 6.3 Update `CHANGELOG.md` with bugfix entry
+
+## 7. Pull Request
+
+- [ ] 7.1 Push branch and open PR to `dev`
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.30.2"
+version = "0.30.3"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"

diff --git a/setup.py b/setup.py
@@ -7,7 +7,7 @@
 if __name__ == "__main__":
     _setup = setup(
         name="specfact-cli",
-        version="0.30.2",
+        version="0.30.3",
         description=(
             "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with "
             "validation and contract enforcement for new projects and long-lived codebases."

diff --git a/src/__init__.py b/src/__init__.py
@@ -3,4 +3,4 @@
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.30.1"
+__version__ = "0.30.3"
diff --git a/src/specfact_cli/__init__.py b/src/specfact_cli/__init__.py
@@ -8,6 +8,6 @@
 - Supporting agile ceremonies and team workflows
 """
 
-__version__ = "0.30.2"
+__version__ = "0.30.3"
 
 __all__ = ["__version__"]