nold-ai · djm81 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: verify-module-signatures
+        name: Verify module signatures and version bumps
+        entry: hatch run ./scripts/verify-modules-signature.py --require-signature --enforce-version-bump
+        language: system
+        pass_filenames: false
+        always_run: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,29 @@ All notable changes to this project will be documented in this file.
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
 
+---
+
+## [0.37.5] - 2026-02-25
+
+### Fixed
+
+- Backlog refine/write-back now resolves ADO custom field targets deterministically across mapped canonical fields, preventing fallback to unintended defaults (for example Story Points field drift).
+- Backlog refine tmp import contract and parser guidance were aligned across backlog prompts, including mandatory stable `ID` usage and provider-specific structure requirements.
+- ADO markdown write-back and extraction handling were hardened: markdown-supported fields are formatted consistently, duplicate description headings are stripped, and rich-text normalization preserves line breaks and non-HTML angle-bracket content.
+- Refine import/update safeguards now prevent title pollution (`## Item ...`) and reject significant silent content loss during bulk refinement flows.
+- Template and mapping steering for ADO now prefers user-story templates where applicable and includes explicit process/framework selection behavior in mapping workflows.
+- Backlog read commands now support `--state any` and `--assignee any` semantics to explicitly disable those filters and avoid confusing empty results caused by hidden defaults.
+- Fixed a `daily` regression where explicit `--state any` / `--assignee any` still fell back to standup defaults (`open`/configured assignee) instead of disabling filters.
+- GitHub backlog create/type assignment now falls back `story -> feature` by default when native `Story` type is not available in the repository, while preserving explicit mappings when present.
+- ADO transport/write paths were hardened with improved retry/diagnostic behavior and clearer default-filter visibility in command output for production-style environments.
+- Contract-exploration counterexamples were addressed by tightening converter preconditions and timestamp parsing robustness, and by hardening TODO-marker detection against regex edge cases.
+- `specfact module init` command-test assertions now handle isolated user-root output formatting consistently, avoiding brittle path-specific failures in CI and local runs.
+- Enforcement preset factory return-path validation no longer triggers spurious beartype return violations in strict test runs.
+- Addressed integration/unit regressions in backlog command parsing/help wiring and ADO parent-candidate WIQL request handling introduced during hardening.
+- Removed module installer tar extraction deprecation warnings by using safer extraction mode with backward-compatible fallback.
+- Docs site rendering was corrected for linked architecture pages by adding missing Jekyll front matter and replacing non-doc relative links with stable GitHub URLs where appropriate.
+- Eliminated widespread `ValueError: I/O operation on closed file` CLI/E2E failures by rebinding module-level Rich consoles to the active invocation stream at CLI entry, preventing stale closed capture streams across sequential test runs.
+
 ---
 
 ## [0.37.4] - 2026-02-25

diff --git a/README.md b/README.md
@@ -54,6 +54,29 @@ specfact validate sidecar init my-project /path/to/repo
 specfact validate sidecar run my-project /path/to/repo
 ```
 
+### Backlog Bridge (60 seconds)
+
+SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
+
+```bash
+# 1) Initialize backlog config + field mapping
+specfact backlog init-config --force
+specfact backlog map-fields --provider ado --ado-org <org> --ado-project "<project>"
+
+# 2) Run standup/refinement on real backlog scope
+specfact backlog daily ado --ado-org <org> --ado-project "<project>" --state any --assignee any --limit 5
+specfact backlog refine ado --ado-org <org> --ado-project "<project>" --id <work-item-id> --preview
+
+# 3) Keep backlog + spec intent aligned (avoid silent drift)
+specfact policy validate --group-by-item
+```
+
+For GitHub, replace adapter/org/project with:
+`specfact backlog daily github --repo-owner <owner> --repo-name <repo> ...`
+
+Deep dive:
+- **[Backlog Quickstart Demo (GitHub + ADO)](docs/getting-started/tutorial-backlog-quickstart-demo.md)**
+
 **AI IDE quick start**
 
 ```bash

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -134,6 +134,7 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/getting-started/installation/' | relative_url }}">Installation</a></li>
                 <li><a href="{{ '/getting-started/first-steps/' | relative_url }}">First Steps</a></li>
                 <li><a href="{{ '/getting-started/module-bootstrap-checklist/' | relative_url }}">Module Bootstrap Checklist</a></li>
+                <li><a href="{{ '/getting-started/tutorial-backlog-quickstart-demo/' | relative_url }}">Tutorial: Backlog Quickstart Demo</a></li>
                 <li><a href="{{ '/getting-started/tutorial-backlog-refine-ai-ide/' | relative_url }}">Tutorial: Backlog Refine with AI IDE</a></li>
                 <li><a href="{{ '/getting-started/tutorial-daily-standup-sprint-review/' | relative_url }}">Tutorial: Daily Standup and Sprint Review</a></li>
               </ul>
@@ -166,6 +167,7 @@ <h2 class="docs-sidebar-title">
               <ul>
                 <li><a href="{{ '/guides/devops-adapter-integration/' | relative_url }}">DevOps Integration Guide</a></li>
                 <li><a href="{{ '/guides/backlog-refinement/' | relative_url }}">Backlog Refinement</a></li>
+                <li><a href="{{ '/getting-started/tutorial-backlog-quickstart-demo/' | relative_url }}">Backlog Quickstart Demo</a></li>
                 <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
                 <li><a href="{{ '/adapters/github/' | relative_url }}">GitHub Adapter</a></li>
                 <li><a href="{{ '/adapters/azuredevops/' | relative_url }}">Azure DevOps Adapter</a></li>

diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Architecture Docs Index
+description: Index of SpecFact CLI architecture deep-dive documents.
+permalink: /architecture/
+---
+
 # SpecFact CLI Architecture Documentation
 
 Architecture documents in this folder describe the current implementation and clearly separate planned features.

diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
@@ -55,6 +55,7 @@ uvx specfact-cli@latest plan init my-project --interactive
 - 📖 **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](tutorial-openspec-speckit.md)** ⭐ **NEW** - Complete beginner-friendly tutorial
 - 📖 **[DevOps Backlog Integration](../guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows
 - 📖 **[Backlog Refinement](../guides/backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven refinement for standardizing work items
+- 📖 **[Tutorial: Backlog Quickstart Demo (GitHub + ADO)](tutorial-backlog-quickstart-demo.md)** 🆕 - Short end-to-end demo: `init-config`, `map-fields`, `daily`, `refine`, plus create/check loop
 - 📖 **[Tutorial: Backlog Refine with AI IDE](tutorial-backlog-refine-ai-ide.md)** 🆕 - End-to-end for agile DevOps teams: slash prompt, story quality, underspecification, splitting, DoR, custom templates
 - 📖 **[Tutorial: Daily Standup and Sprint Review](tutorial-daily-standup-sprint-review.md)** 🆕 - End-to-end daily standup: auto-detect repo (GitHub/ADO), view standup table, post comment, interactive, Copilot export
 - 📖 **[Use Cases](../guides/use-cases.md)** - See real-world examples

diff --git a/docs/getting-started/tutorial-backlog-quickstart-demo.md b/docs/getting-started/tutorial-backlog-quickstart-demo.md
@@ -0,0 +1,254 @@
+---
+layout: default
+title: Tutorial - Backlog Quickstart Demo (GitHub + ADO)
+description: Short end-to-end demo for backlog init-config, map-fields, daily, and refine on GitHub and Azure DevOps.
+permalink: /getting-started/tutorial-backlog-quickstart-demo/
+---
+
+# Tutorial: Backlog Quickstart Demo (GitHub + ADO)
+
+This is a short, copy/paste-friendly demo for new users covering:
+
+1. `specfact backlog init-config`
+2. `specfact backlog map-fields`
+3. `specfact backlog daily`
+4. `specfact backlog refine` (GitHub + ADO)
+
+It also includes a minimal create/check loop using `specfact backlog add`.
+
+Preferred ceremony aliases:
+
+- `specfact backlog ceremony standup` (same behavior as `backlog daily`)
+- `specfact backlog ceremony refinement` (same behavior as `backlog refine`)
+
+## Targets Used in This Demo
+
+- **GitHub**: `nold-ai/specfact-demo-repo`
+- **Azure DevOps**: `dominikusnold/Specfact CLI`
+
+## Prerequisites
+
+- SpecFact CLI installed
+- Auth configured:
+
+```bash
+specfact auth github
+specfact auth azure-devops
+specfact auth status
+```
+
+Expected status should show both providers as valid.
+
+## 1) Initialize Backlog Config
+
+```bash
+specfact backlog init-config --force
+```
+
+This creates `.specfact/backlog-config.yaml`.
+
+## 2) Map Fields (ADO)
+
+Run field mapping for your ADO project. This command is interactive by design.
+
+```bash
+specfact backlog map-fields \
+  --provider ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --ado-framework scrum
+```
+
+Notes:
+
+- Select the process style intentionally (`--ado-framework scrum|agile|safe|kanban|default`).
+- Mapping is written to `.specfact/templates/backlog/field_mappings/ado_custom.yaml`.
+- Provider context is updated in `.specfact/backlog.yaml`.
+
+Optional reset:
+
+```bash
+specfact backlog map-fields \
+  --provider ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --ado-framework scrum \
+  --reset
+```
+
+## 3) Daily Standup View (Check Backlog Read)
+
+GitHub:
+
+```bash
+specfact backlog daily github \
+  --repo-owner nold-ai \
+  --repo-name specfact-demo-repo \
+  --state open \
+  --limit 5
+```
+
+Disable default state/assignee filters explicitly (for exact ID checks):
+
+```bash
+specfact backlog daily github \
+  --repo-owner nold-ai \
+  --repo-name specfact-demo-repo \
+  --id 28 \
+  --state any \
+  --assignee any
+```
+
+ADO:
+
+```bash
+specfact backlog daily ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --limit 5
+```
+
+## 4) Refine Workflow (Preview + Tmp Export/Import)
+
+GitHub export:
+
+```bash
+specfact backlog refine github \
+  --repo-owner nold-ai \
+  --repo-name specfact-demo-repo \
+  --limit 3 \
+  --export-to-tmp
+```
+
+ADO export:
+
+```bash
+specfact backlog refine ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --limit 3 \
+  --export-to-tmp
+```
+
+After refining in your AI IDE, import and write back:
+
+```bash
+# GitHub
+specfact backlog refine github \
+  --repo-owner nold-ai \
+  --repo-name specfact-demo-repo \
+  --import-from-tmp \
+  --write
+
+# ADO
+specfact backlog refine ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --import-from-tmp \
+  --write
+```
+
+### Required Tmp File Contract (Important)
+
+For `--import-from-tmp`, each item block must keep:
+
+- `## Item N: <title>`
+- `**ID**: <original-id>` (mandatory, unchanged)
+- `**URL**`, `**State**`, `**Provider**`
+- `**Body**:` fenced with ```markdown
+
+Minimal scaffold:
+
+````markdown
+## Item 1: Example title
+
+**ID**: 123
+**URL**: https://example
+**State**: Active
+**Provider**: ado
+
+**Body**:
+```markdown
+## As a
+...
+```
+````
+
+Do not rename labels and do not remove details during refinement.
+
+## 5) Minimal Create + Check Loop
+
+Create test issue/work item:
+
+```bash
+# GitHub create
+specfact backlog add \
+  --adapter github \
+  --project-id nold-ai/specfact-demo-repo \
+  --type story \
+  --title "SpecFact demo smoke test $(date +%Y-%m-%d-%H%M)" \
+  --body "Demo item created by quickstart." \
+  --acceptance-criteria "Demo item exists and is retrievable" \
+  --non-interactive
+
+# ADO create
+specfact backlog add \
+  --adapter ado \
+  --project-id "dominikusnold/Specfact CLI" \
+  --type story \
+  --title "SpecFact demo smoke test $(date +%Y-%m-%d-%H%M)" \
+  --body "Demo item created by quickstart." \
+  --acceptance-criteria "Demo item exists and is retrievable" \
+  --non-interactive
+```
+
+Then verify retrieval by ID using `daily` or `refine --id <id>`.
+
+## Quick Troubleshooting
+
+- DNS/network errors (`api.github.com`, `dev.azure.com`): verify outbound network access.
+- Auth errors: re-run `specfact auth status`.
+- ADO mapping issues: re-run `backlog map-fields` and confirm `--ado-framework` is correct.
+- Refine import mismatch: check `**ID**` was preserved exactly.
+
+## ADO Hardening Profile (Corporate Networks)
+
+For unstable corporate VPN/proxy/firewall paths, use this reliability profile.
+
+### Runtime behavior now hardened in CLI
+
+- ADO `daily`/`refine` read paths now retry transient transport failures (`ConnectionError`, reset/disconnect, timeout).
+- Retry policy also covers retryable HTTP statuses (`429`, `500`, `502`, `503`, `504`) with backoff.
+- Hardened paths include:
+  - WIQL query execution
+  - Work-item batch fetch
+  - Iteration/team lookup
+  - Work-item comments fetch
+
+### Operational command recommendations
+
+Use explicit provider context and bounded scope to reduce query fragility:
+
+```bash
+# Daily: explicit scope
+specfact backlog daily ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --state New \
+  --limit 20
+
+# Refine: small batches first, then scale
+specfact backlog refine ado \
+  --ado-org dominikusnold \
+  --ado-project "Specfact CLI" \
+  --state New \
+  --limit 5 \
+  --export-to-tmp
+```
+
+If current iteration auto-detection is unreliable in your environment, pass explicit filters (`--state`, `--sprint`, `--iteration`) rather than relying on defaults.
+
+### Create flow reliability notes
+
+- `backlog add` uses safe no-replay behavior for create operations to avoid accidental duplicate work-item creation on ambiguous transport failures.
+- If create returns an ambiguous transport error, check ADO for the title before retrying manually.
diff --git a/docs/guides/backlog-refinement.md b/docs/guides/backlog-refinement.md
@@ -430,6 +430,7 @@ specfact backlog ceremony refinement <ADAPTER> [OPTIONS]
 **Options**:
 
 - `--search`, `-s` - Search query to filter backlog items
+- `--state any` / `--assignee any` - Explicitly disable state/assignee filtering when needed (for example ID-specific runs).
 - `--template`, `-t` - Target template ID (default: auto-detect)
 - `--ignore-refined` / `--no-ignore-refined` - When using `--limit N`, apply limit to items that need refinement (default: ignore already-refined items so you see N items that actually need work)
 - `--id` - Refine only the backlog item with the given issue or work item ID