fix(backlog): harden refine writeback, prompts, and any-filter semantics

[djm81]

Description

This PR delivers backlog-core-06-refine-custom-field-writeback end-to-end hardening across backlog refine/daily flows (ADO + GitHub), parser/prompt contracts, markdown rendering, and module-signing/version guardrails.

Key outcomes:

• deterministic ADO custom field writeback (story points + mapped canonical fields)
• strict tmp import ID contract (mandatory stable **ID** in imported blocks)
• prompt/template alignment with parser/provider expectations
• markdown-safe ADO writeback/extraction normalization
• prevention of title/body pollution and silent content loss
• template steering and map-fields process/framework handling improvements
• true no-filter semantics for --state any / --assignee any in backlog daily/refine
• docs + quickstart updates (README + docs landing/sidebar/tutorial)
• hardened module signing/verification scripts enforcing version bump policy

Fixes #310

New Features #310

Contract References:

• backlog command/filter normalization and scope resolution contracts in src/specfact_cli/modules/backlog/src/commands.py
• adapter mapping/writeback contracts in src/specfact_cli/adapters/ado.py and mapper layer

Type of Change

Please check all that apply:

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔒 Contract enforcement (adding/updating @icontract decorators)
• 🧪 Test enhancement (scenario tests, property-based tests)
• 🔧 Refactoring (code improvement without functionality change)

Contract-First Testing Evidence

Required for all changes affecting CLI commands or public APIs:

Contract Validation

• Runtime contracts added/updated (@icontract decorators on public APIs)
• Type checking enforced (@beartype decorators applied)
• CrossHair exploration completed: hatch run contract-test-exploration
• Contract violations reviewed and addressed

Test Execution

• Contract validation: hatch run contract-test-contracts ✅
• Contract exploration: hatch run contract-test-exploration ✅
• Scenario tests: hatch run contract-test-scenarios ✅
• Full test suite: hatch run contract-test-full ✅

Test Quality

• CLI commands tested with typer test client
• Edge cases covered with Hypothesis/property and regression tests where applicable
• Error handling tested with invalid inputs
• Rich console output verified manually and via tests

How Has This Been Tested?

Contract-First Approach: contract exploration, targeted regression tests, and broad integration/e2e slices were used to validate behavior changes.

Manual Testing

• Tested CLI commands manually
• Verified rich console output
• Tested with different input scenarios
• Checked error messages for clarity

Automated Testing

• Contract validation passes
• Property-based tests cover edge cases
• Scenario tests cover user workflows
• All existing tests still pass locally

Test Environment

• Python version: 3.11 / 3.12
• OS: Linux (Ubuntu)

Checklist

• My code follows the style guidelines (PEP 8, ruff format, isort)
• I have performed a self-review of my code
• I have added/updated contracts (@icontract, @beartype)
• I have added/updated docstrings (Google style)
• I have made corresponding changes to documentation
• My changes generate no new warnings (basedpyright, ruff, pylint)
• All tests pass locally
• I have added tests that prove my fix/feature works
• Any dependent changes have been merged

Quality Gates Status

• Type checking ✅ (hatch run type-check)
• Linting ✅ (hatch run lint)
• Contract validation ✅ (hatch run contract-test-contracts)
• Contract exploration ✅ (hatch run contract-test-exploration)
• Scenario tests ✅ (hatch run contract-test-scenarios)

Screenshots/Recordings (if applicable)

Backlog daily real-world verification after any fix:

• specfact backlog daily ado --ado-org dominikusnold --ado-project "Specfact CLI" --state any --assignee any
• Output confirms state=— (explicit), assignee=— (explicit) and returns expected items.

OpenSpec Artifacts

• Change: openspec/changes/backlog-core-06-refine-custom-field-writeback/
• TDD evidence: TDD_EVIDENCE.md
• Change validation: CHANGE_VALIDATION.md
• Tasks marked complete including PR prep (4.5).