diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63162f75..8fcb0d7e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,13 @@ All notable changes to this project will be documented in this file.
---
+## [Unreleased]
+
+### Added
+
+- Documentation: `docs/reference/documentation-url-contract.md` and navigation links describing how core and modules published URLs relate; OpenSpec spec updates for cross-site linking expectations.
+- Documentation: converted 20 module-owned guide and tutorial pages under `docs/` to thin handoff summaries with canonical links to `modules.specfact.io`; added `docs/reference/core-to-modules-handoff-urls.md` mapping core permalinks to modules URLs.
+
## [0.42.6] - 2026-03-26
### Fixed
diff --git a/docs/README.md b/docs/README.md
index ac641744..8770f112 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -35,6 +35,10 @@ Use the canonical modules docs site for:
The canonical modules docs site is currently published at `https://modules.specfact.io/`.
This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance.
+## Cross-site contract
+
+- [Documentation URL contract (core and modules)](reference/documentation-url-contract.md) — linking rules vs `modules.specfact.io`
+
## Core Entry Points
- [Docs Home](index.md)
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 87e3f30b..54121368 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -164,6 +164,7 @@ Reference
+ - Docs URL contract (core vs modules)
- Command Reference
- Module Categories
- Module Contracts
diff --git a/docs/getting-started/tutorial-backlog-quickstart-demo.md b/docs/getting-started/tutorial-backlog-quickstart-demo.md
index e97cb301..a89baac7 100644
--- a/docs/getting-started/tutorial-backlog-quickstart-demo.md
+++ b/docs/getting-started/tutorial-backlog-quickstart-demo.md
@@ -1,277 +1,14 @@
---
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.
+description: Handoff to the backlog quickstart demo tutorial on the modules documentation site.
permalink: /getting-started/tutorial-backlog-quickstart-demo/
---
-# Tutorial: Backlog Quickstart Demo (GitHub + ADO)
+# Tutorial — backlog quickstart demo
+A short end-to-end demo for backlog init, field mapping, daily flow, and refinement on GitHub and Azure DevOps. Copy-paste steps, screenshots, and troubleshooting are kept current on the modules site.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** Accounts and tokens for your tracker; [Installation](https://docs.specfact.io/getting-started/installation/) completed.
-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 backlog auth github
-specfact backlog auth azure-devops
-specfact backlog 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. Start with automatic mapping and use interactive mode only if required fields remain unresolved.
-
-```bash
-# Automatic mapping for repeatable setup
-specfact backlog map-fields \
- --provider ado \
- --ado-org dominikusnold \
- --ado-project "Specfact CLI" \
- --ado-framework scrum \
- --non-interactive
-
-# Interactive mapping / manual correction
-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`.
-- Required fields, selected work item type, and constrained values are persisted in `.specfact/backlog-config.yaml`.
-- `--non-interactive` fails fast with guidance to rerun interactive mapping if required fields remain unresolved.
-
-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: `
-- `**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" \
- --custom-field category=Architecture \
- --custom-field subcategory="Runtime validation" \
- --non-interactive
-```
-
-Then verify retrieval by ID using `daily` or `refine --id <id>`.
-
-For ADO projects with required custom fields or picklists:
-
-- run `backlog map-fields` first so `backlog add` has required-field and allowed-values metadata
-- use repeatable `--custom-field key=value` for mapped custom fields
-- non-interactive `backlog add` rejects invalid picklist values before create and prints accepted values
-
-## Quick Troubleshooting
-
-- DNS/network errors (`api.github.com`, `dev.azure.com`): verify outbound network access.
-- Auth errors: re-run `specfact backlog auth status`.
-- ADO mapping issues: re-run `backlog map-fields` and confirm `--ado-framework` is correct. Use interactive mode if auto-mapping cannot resolve required fields.
-- 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.
+**Full tutorial on the canonical modules docs site:** [Backlog quickstart demo](https://modules.specfact.io/getting-started/tutorial-backlog-quickstart-demo/)
diff --git a/docs/getting-started/tutorial-backlog-refine-ai-ide.md b/docs/getting-started/tutorial-backlog-refine-ai-ide.md
index 4d5b72d2..ba32f05f 100644
--- a/docs/getting-started/tutorial-backlog-refine-ai-ide.md
+++ b/docs/getting-started/tutorial-backlog-refine-ai-ide.md
@@ -1,185 +1,14 @@
---
layout: default
title: Tutorial - Backlog Refine with Your AI IDE
-description: Integrate SpecFact CLI backlog refinement with your AI IDE. Improve story quality, underspec/overspec, split stories, fix ambiguities, respect DoR, and use custom template mapping.
+description: Handoff to backlog refine with AI IDE tutorial on the modules documentation site.
permalink: /getting-started/tutorial-backlog-refine-ai-ide/
---
-# Tutorial: Backlog Refine with Your AI IDE (Agile DevOps Teams)
+# Tutorial — backlog refine with your AI IDE
+Learn how to combine SpecFact backlog refinement with your AI IDE—story quality, splitting, and template-aware writeback. The full tutorial with IDE-specific notes lives on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** IDE integration from `specfact init ide` if you use slash commands; [Authentication](https://docs.specfact.io/reference/authentication/) for your backlog provider.
-This tutorial walks agile DevOps teams through integrating SpecFact CLI backlog refinement with their AI IDE (Cursor, VS Code + Copilot, Claude Code, etc.) using the interactive slash prompt. You will improve backlog story quality, make informed decisions about underspecification, split stories when too big, fix ambiguities, respect Definition of Ready (DoR), and optionally use custom template mapping for advanced teams.
-
-Preferred command path is `specfact backlog ceremony refinement ...`. The legacy `specfact backlog refine ...` path remains supported for compatibility.
-
-**Time**: ~20–30 minutes
-**Outcome**: End-to-end flow from raw backlog items to template-compliant, DoR-ready stories via your AI IDE.
-
----
-
-## What You'll Learn
-
-- Run `specfact backlog ceremony refinement` and use the **slash prompt** in your AI IDE for interactive refinement
-- Use the **interactive feedback loop**: present story → assess specification level (under-/over-/fit) → list ambiguities → ask clarification → re-refine until approved
-- Improve story quality: identify **underspecified** (missing AC, vague scope), **overspecified** (too many sub-steps, implementation detail), or **fit-for-scope** stories
-- Decide when to **split** stories that are too big
-- Respect **Definition of Ready (DoR)** once defined in your team
-- For advanced teams: point to **custom template mapping** (e.g. ADO custom fields) when required
-
----
-
-## Prerequisites
-
-- SpecFact CLI installed (`uvx specfact-cli@latest` or `pip install specfact-cli`)
-- Access to a backlog (GitHub repo or Azure DevOps project)
-- AI IDE with slash commands (Cursor, VS Code + Copilot, etc.)
-- Optional: `specfact init ide --ide cursor` (or your IDE) so the backlog-refine slash command is available
-
----
-
-## Step 1: Run Backlog Refine and Get Items
-
-From your **repo root** (or where your backlog lives):
-
-```bash
-# GitHub: org/repo are auto-detected from git remote when run from a GitHub clone
-specfact backlog ceremony refinement github --search "is:open label:feature" --limit 5 --preview
-
-# Or export to a temp file for your AI IDE to process (recommended for interactive loop)
-specfact backlog ceremony refinement github --export-to-tmp --search "is:open label:feature" --limit 5
-```
-
-**Auto-detect from clone**: When you run from a **GitHub** clone (e.g. `https://github.com/owner/repo` or `git@github.com:owner/repo.git`), SpecFact infers `repo_owner` and `repo_name` from `git remote get-url origin`—no `--repo-owner`/`--repo-name` needed. When you run from an **Azure DevOps** clone (e.g. `https://dev.azure.com/org/project/_git/repo`; SSH keys: `git@ssh.dev.azure.com:v3/org/project/repo`; other SSH: `user@dev.azure.com:v3/org/project/repo`), org and project are inferred. Override with `.specfact/backlog.yaml`, env vars (`SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_ADO_ORG`, etc.), or CLI options when not in the repo or to override.
-
-If you're **not** in a clone, pass adapter context explicitly:
-
-```bash
-specfact backlog ceremony refinement github --repo-owner OWNER --repo-name REPO --search "is:open label:feature" --limit 5 --preview
-# or ADO:
-specfact backlog ceremony refinement ado --ado-org ORG --ado-project PROJECT --state Active --limit 5 --preview
-```
-
-- Use `--ignore-refined` (default) so `--limit` applies to items that **need** refinement
-- Use `--id ISSUE_ID` to refine a **single** item by ID
-- Use `--check-dor` when your team has a DoR config in `.specfact/dor.yaml`
-
----
-
-## Step 2: Invoke the Slash Prompt in Your AI IDE
-
-In Cursor, VS Code, or your IDE:
-
-1. Open the **slash command** for backlog refinement (e.g. `/specfact.backlog-refine` or the equivalent in your IDE).
-2. Pass the same arguments you would use in the CLI, for example:
- - `/specfact.backlog-refine --adapter github --repo-owner OWNER --repo-name NAME --labels feature --limit 5`
-
-These slash prompts are provided by the installed backlog bundle, not by the permanent core CLI package.
-
-The AI will use the **SpecFact Backlog Refinement** prompt, which includes:
-
-- Template-driven refinement (user story, defect, spike, enabler)
-- **Interactive refinement (Copilot mode)**: present story → list ambiguities → ask clarification → re-refine until you approve
-- **Specification level**: for each story, the AI assesses whether it is **under-specified**, **over-specified**, or **fit for scope and intent**, with evidence (missing AC, vague scope, too many sub-steps, etc.)
-
----
-
-## Step 3: Use the Interactive Feedback Loop
-
-For each story, the AI should:
-
-1. **Present** the refined story (Title, Body, Acceptance Criteria, Metrics) in a clear, scannable format.
-2. **Assess specification level**:
- - **Under-specified**: Missing acceptance criteria, vague scope, unclear “so that” or user value. List what’s missing.
- - **Over-specified**: Too much implementation detail, too many sub-steps for one story, or solution prescribed instead of outcome. Suggest what to trim or move.
- - **Fit for scope and intent**: Clear persona, capability, benefit, and testable AC; appropriate size. State briefly why it’s ready.
-3. **List ambiguities** or open questions (e.g. conflicting assumptions, unclear priority).
-4. **Ask** you (PO/stakeholder): “Do you want any changes? Any ambiguities to resolve? Should this story be split?”
-5. **Re-refine** if you give feedback, then repeat from “Present” until you **explicitly approve** (e.g. “looks good”, “approved”).
-6. Only after approval: mark the story done and move to the next. Do **not** update the backlog item until that story is approved.
-
-This loop ensures the DevOps team sees **underspecification** (and over-specification) explicitly and can improve story quality and respect DoR before committing to the backlog.
-
----
-
-## Step 4: Respect Definition of Ready (DoR)
-
-If your team uses DoR:
-
-1. Create or edit `.specfact/dor.yaml` in the repo (e.g. require story_points, priority, business_value, acceptance_criteria).
-2. Run refine with `--check-dor`:
-
- ```bash
- specfact backlog ceremony refinement github --repo-owner OWNER --repo-name REPO --check-dor --labels feature
- ```
-
-3. In the interactive loop, treat DoR as part of “fit for scope”: if the refined story doesn’t meet DoR (e.g. missing AC or story points), the AI should flag it as under-specified or not ready and suggest what to add.
-
----
-
-## Step 5: When to Split a Story
-
-During the loop, if the AI or you identify that a story is **too big** (e.g. multiple capabilities, many sub-steps, or clearly two user outcomes):
-
-- The AI should state: “This story may be too large; consider splitting by [capability / user outcome / step].”
-- You decide: either split into two (or more) stories and refine each separately, or keep as one and trim scope. Only after that decision should the story be marked approved and written back.
-
----
-
-## Step 6: Write Back (When Ready)
-
-When you’re satisfied with the refined content:
-
-```bash
-# If you used --export-to-tmp, save the refined file as ...-refined.md, then:
-# (From repo root, org/repo or org/project are auto-detected from git remote)
-specfact backlog ceremony refinement github --import-from-tmp --write
-
-# Or run refine interactively with --write (use with care; confirm each item)
-specfact backlog ceremony refinement github --write --labels feature --limit 3
-```
-
-Use `--preview` (default) until you’re confident; use `--write` only when you want to update the remote backlog.
-
----
-
-## Step 7: Advanced Teams — Custom Template Mapping
-
-If your team uses **custom fields** (e.g. Azure DevOps custom process templates):
-
-1. **ADO**: Add a custom field mapping file and point the CLI to it:
-
- ```bash
- specfact backlog ceremony refinement ado --ado-org ORG --ado-project PROJECT \
- --custom-field-mapping .specfact/templates/backlog/field_mappings/ado_custom.yaml \
- --state Active
- ```
-
-2. See **[Template Customization](../guides/template-customization.md)** and **[Custom Field Mapping](../guides/custom-field-mapping.md)** for defining templates and mapping ADO fields.
-3. The same **interactive loop and specification-level assessment** (under-/over-/fit) apply; the AI should use your template’s required sections when assessing “fit for scope”.
-
----
-
-## Summary
-
-| Goal | How |
-|-----------------------------|-----|
-| Improve story quality | Use the interactive loop; fix under-/over-specification and ambiguities before approving. |
-| Know if a story is under/over/fit | AI assesses each story and lists evidence; you decide to add detail, split, or accept. |
-| Split stories that are too big | AI suggests splitting when appropriate; you refine each new story separately. |
-| Respect DoR | Use `--check-dor` and treat DoR as part of “fit for scope” in the loop. |
-| Custom templates / mapping | Use `--custom-field-mapping` (ADO) and custom templates; see Template Customization and Custom Field Mapping guides. |
-
----
-
-## Related Documentation
-
-- **[Backlog Refinement Guide](../guides/backlog-refinement.md)** — Full reference: templates, options, export/import, DoR
-- **[Story scope and specification level](../guides/backlog-refinement.md#story-scope-and-specification-level)** — Underspecification, over-specification, fit-for-scope
-- **[Definition of Ready (DoR)](../guides/backlog-refinement.md#step-45-definition-of-ready-dor-validation-optional)** — DoR configuration and validation
-- **[Template Customization](../guides/template-customization.md)** — Custom templates for advanced teams
-- **[Custom Field Mapping](../guides/custom-field-mapping.md)** — ADO custom field mapping
-- **[IDE Integration](../guides/ide-integration.md)** — Set up slash commands in Cursor, VS Code, etc.
+**Full tutorial on the canonical modules docs site:** [Backlog refine with AI IDE](https://modules.specfact.io/getting-started/tutorial-backlog-refine-ai-ide/)
diff --git a/docs/getting-started/tutorial-daily-standup-sprint-review.md b/docs/getting-started/tutorial-daily-standup-sprint-review.md
index f181854f..2ce2c856 100644
--- a/docs/getting-started/tutorial-daily-standup-sprint-review.md
+++ b/docs/getting-started/tutorial-daily-standup-sprint-review.md
@@ -1,225 +1,14 @@
---
layout: default
title: Tutorial - Daily Standup and Sprint Review with SpecFact CLI
-description: End-to-end daily standup and sprint review using specfact backlog ceremony standup. Auto-detect repo from git (GitHub or Azure DevOps), view standup table, post standup comments, use interactive mode and Copilot export.
+description: Handoff to daily standup and sprint review tutorial on the modules documentation site.
permalink: /getting-started/tutorial-daily-standup-sprint-review/
---
-# Tutorial: Daily Standup and Sprint Review with SpecFact CLI
+# Tutorial — daily standup and sprint review
+Walk through standup and sprint review flows using SpecFact ceremony commands, including repo detection and optional comment post-back. Detailed steps and platform notes are on the modules documentation site.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Quickstart](https://docs.specfact.io/getting-started/quickstart/); backlog sync configured for your repository.
-This tutorial walks you through a complete **daily standup and sprint review** workflow using SpecFact CLI: view your backlog items, optionally post standup comments to issues, use interactive step-through and Copilot export—with **no need to pass org/repo or org/project** when you run from your cloned repo.
-
-Preferred command path is `specfact backlog ceremony standup ...`. The legacy `specfact backlog daily ...` path remains supported for compatibility.
-
-**Time**: ~10–15 minutes
-**Outcome**: End-to-end flow from "clone + auth" to standup view, optional post, interactive review, and Copilot-ready export.
-
----
-
-## What You'll Learn
-
-- Run **`specfact backlog ceremony standup`** and see your standup table (assigned + unassigned items) with **auto-detected** GitHub org/repo or Azure DevOps org/project from the git remote
-- Use **`.specfact/backlog.yaml`** or environment variables when you're not in the repo (e.g. CI) or to override
-- **Post a standup comment** to the first (or selected) item with `--yesterday`, `--today`, `--blockers` and `--post`
-- Use **`--interactive`** for step-by-step story review (arrow-key selection, full detail, latest comment + hidden-count hint, and optional in-flow posting on the selected story)
-- Use **`--copilot-export <path>`** to write a Markdown summary for Copilot slash-command during standup;
- add **`--comments`** (alias **`--annotations`**) to include descriptions and comment annotations when
- the adapter supports fetching comments
-- Use **`--summarize`** or **`--summarize-to <path>`** to output a **prompt** (instruction + filter context
- + standup data) for a slash command (e.g. `specfact.daily`) or copy-paste to Copilot to **generate a
- standup summary**; add **`--comments`**/**`--annotations`** to include comment annotations in the prompt.
- The prompt content is always **normalized to Markdown-only text** (no raw HTML tags or HTML entities) so
- ADO-style HTML descriptions/comments and GitHub/Markdown content render consistently.
-- Use the **`specfact.backlog-daily`** (or `specfact.daily`) slash prompt for interactive walkthrough with the DevOps team story-by-story (focus, issues, open questions, discussion notes as comments)
-- The daily standup slash prompt is provided by the installed backlog bundle rather than the permanent core CLI package
-- Filter by **`--assignee`**, **`--sprint`** / **`--iteration`**, **`--search`**, **`--release`**, **`--id`**, **`--first-issues`** / **`--last-issues`**, **`--blockers-first`**, and optional **`--suggest-next`**
-
----
-
-## Prerequisites
-
-- SpecFact CLI installed (`uvx specfact-cli@latest` or `pip install specfact-cli`)
-- **Authenticated** to your backlog provider: `specfact backlog auth github` or Azure DevOps (PAT in env)
-- A **clone** of your repo (GitHub or Azure DevOps) so the CLI can auto-detect org/repo or org/project from `git remote origin`
-
----
-
-## Step 1: Run Daily Standup (Auto-Detect Repo)
-
-From your **repo root** (where `.git` lives):
-
-```bash
-# GitHub: org/repo are inferred from git remote origin
-specfact backlog ceremony standup github
-
-# Azure DevOps: org/project are inferred from git remote origin
-# (e.g. https://dev.azure.com/... or git@ssh.dev.azure.com:v3/... for SSH keys; user@dev.azure.com:v3/... if not using SSH keys)
-specfact backlog ceremony standup ado
-```
-
-**What you see**:
-
-- **Daily standup** table: your assigned (or filtered) items with ID, title, status, last updated, yesterday/today/blockers columns
-- **Pending / open for commitment**: unassigned items in the same scope
-
-**No `--repo-owner`/`--repo-name` (GitHub) or `--ado-org`/`--ado-project` (ADO) needed** when the repo was cloned from that provider—SpecFact reads `git remote get-url origin` and infers the context.
-
-If you're **not** in a clone (e.g. different directory), use one of:
-
-- **`.specfact/backlog.yaml`** in the project (see [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml))
-- **Environment variables**: `SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_GITHUB_REPO_NAME` or `SPECFACT_ADO_ORG`, `SPECFACT_ADO_PROJECT`
-- **CLI options**: `--repo-owner` / `--repo-name` or `--ado-org` / `--ado-project`
-
----
-
-## Step 2: Filter and Scope
-
-Narrow the list to your sprint or assignee:
-
-```bash
-# My items only (GitHub: login; ADO: current user)
-specfact backlog ceremony standup github --assignee me
-
-# Current sprint (when adapter supports it, e.g. ADO)
-specfact backlog ceremony standup ado --sprint current
-
-# Open items, limit 10, blockers first
-specfact backlog ceremony standup github --state open --limit 10 --blockers-first
-```
-
-Default scope is **state=open**, **limit=20**; overridable via `SPECFACT_STANDUP_STATE`, `SPECFACT_STANDUP_LIMIT`, or `.specfact/standup.yaml`.
-
----
-
-## Step 3: Post a Standup Comment (Optional)
-
-To add a **standup comment** to the **first** item in the list, pass **values** for yesterday/today/blockers and `--post`:
-
-```bash
-specfact backlog ceremony standup github \
- --yesterday "Worked on daily standup and progress support" \
- --today "Will add tests and docs" \
- --blockers "None" \
- --post
-```
-
-**Expected**: The CLI posts a comment on that item's issue (GitHub issue or ADO work item) with a standup block (Yesterday / Today / Blockers). You'll see: `✓ Standup comment posted to story <id>: <issue URL>`.
-
-**Important**: You must pass **values** for at least one of `--yesterday`, `--today`, or `--blockers`. Using `--post` alone (or with flags but no text) will prompt you to add values; see the in-command message and help.
-
----
-
-## Step 4: Interactive Step-Through (Optional)
-
-For a **refine-like** walkthrough (select item → view full detail → next/previous/back/exit):
-
-```bash
-specfact backlog ceremony standup github --interactive
-```
-
-- Use the menu to **select** an item (arrow keys).
-- View **full detail** (description, acceptance criteria, standup fields, and comment context). Interactive detail shows the **latest comment only** plus a hint when older comments exist.
-- Choose **Next story**, **Previous story**, **Post standup update** (posts to the currently selected story), **Back to list**, or **Exit**.
-
-Use **`--suggest-next`** to show a suggested next item by value score (business value / (story points × priority)) when the data is available.
-
----
-
-## Step 5: Export for Copilot (Optional)
-
-To feed a **summary file** into your AI IDE (e.g. for a Copilot slash-command during standup):
-
-```bash
-specfact backlog ceremony standup github --copilot-export ./standup-summary.md --comments
-```
-
-The file contains one section per item (ID, title, status, assignees, last updated, progress, blockers).
-With `--comments`/`--annotations`, it also includes the item description and comment annotations when the
-adapter supports fetching comments. You can open it in your IDE and use it with Copilot. Same scope as
-the standup table (state, assignee, limit, etc.).
-
----
-
-## Step 6: Standup Summary Prompt (Optional)
-
-To get a **prompt** you can paste into Copilot or feed to a slash command (e.g. `specfact.daily`) so an AI can **generate a short standup summary** (e.g. "Today: 3 in progress, 1 blocked, 2 pending commitment"):
-
-```bash
-# Print prompt to stdout (copy-paste to Copilot). In an interactive terminal, SpecFact renders a
-# Markdown-formatted view; in CI/non-interactive environments the same normalized Markdown is printed
-# without ANSI formatting.
-specfact backlog ceremony standup github --summarize --comments
-
-# Write prompt to a file (e.g. for slash command). The file always contains plain Markdown-only content
-# (no raw HTML, no ANSI control codes), suitable for IDE slash commands or copy/paste into Copilot.
-specfact backlog ceremony standup github --summarize-to ./standup-prompt.md --comments
-```
-
-The output includes an instruction to generate a standup summary, the applied filter context (adapter,
-state, sprint, assignee, limit), and the same per-item data as `--copilot-export`. With
-`--comments`/`--annotations`, the prompt includes normalized descriptions and comment annotations when
-supported. Use it with the **`specfact.backlog-daily`** slash prompt for interactive team walkthrough
-(story-by-story, current focus, issues/open questions, discussion notes as comments). The slash prompt
-itself is provided by the installed backlog bundle.
-
----
-
-## End-to-End Example: One Standup Session
-
-1. **Authenticate once** (if not already):
-
- ```bash
- specfact backlog auth github
- ```
-
-2. **Open your repo** and run daily (repo auto-detected):
-
- ```bash
- cd /path/to/your-repo
- specfact backlog ceremony standup github
- ```
-
-3. **Optional: post today's standup** to the first item:
-
- ```bash
- specfact backlog ceremony standup github \
- --yesterday "Implemented backlog context and git inference" \
- --today "Docs and tests for daily standup tutorial" \
- --blockers "None" \
- --post
- ```
-
-4. **Optional: interactive review** or **Copilot export**:
-
- ```bash
- specfact backlog ceremony standup github --interactive --last-comments 3
- # or
- specfact backlog ceremony standup github --copilot-export ./standup.md
- ```
-
----
-
-## Summary
-
-| Goal | How |
-|------|-----|
-| View standup without typing org/repo | Run `specfact backlog ceremony standup github` or `ado` from **repo root**; org/repo or org/project are **auto-detected** from git remote. |
-| Override or use outside repo | Use `.specfact/backlog.yaml`, env vars (`SPECFACT_GITHUB_REPO_OWNER`, etc.), or CLI `--repo-owner`/`--repo-name` or `--ado-org`/`--ado-project`. |
-| Post standup to first item | Use `--yesterday "..."` `--today "..."` `--blockers "..."` and `--post` (values required). |
-| Post standup while reviewing selected story | Use `--interactive` and choose **Post standup update** from navigation. |
-| Step through stories with readable comment context | Use `--interactive`; it shows latest comment + hidden-count hint. Use `--first-comments`/`--last-comments` to tune comment density. |
-| Feed standup into Copilot | Use `--copilot-export <path>`; add `--comments`/`--annotations` for comment annotations. |
-| Generate standup summary via AI (slash command or Copilot) | Use `--summarize` (stdout) or `--summarize-to <path>`; add `--comments`/`--annotations` for comment annotations; use with `specfact.backlog-daily` slash prompt. |
-
----
-
-## Related Documentation
-
-- **[Agile/Scrum Workflows](../guides/agile-scrum-workflows.md)** — Daily standup, iteration/sprint, unassigned items, blockers-first
-- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** — Project backlog context (`.specfact/backlog.yaml`), env vars, **Git fallback (auto-detect from clone)** for GitHub and Azure DevOps
-- **[Backlog Refinement Guide](../guides/backlog-refinement.md)** — Template-driven refinement (complementary to daily standup)
+**Full tutorial on the canonical modules docs site:** [Daily standup and sprint review](https://modules.specfact.io/getting-started/tutorial-daily-standup-sprint-review/)
diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md
index d5def64a..9a663382 100644
--- a/docs/guides/agile-scrum-workflows.md
+++ b/docs/guides/agile-scrum-workflows.md
@@ -2,1053 +2,13 @@
layout: default
title: Agile/Scrum Workflows with SpecFact CLI
permalink: /guides/agile-scrum-workflows/
+description: Handoff to agile and Scrum workflows on the modules documentation site.
---
-# Agile/Scrum Workflows with SpecFact CLI
+# Agile and Scrum workflows
+Use SpecFact with Scrum ceremonies, backlog health, and sprint rhythms—standups, refinement, and reporting. Personas, cadences, and command pairings are described on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Backlog command topology](https://docs.specfact.io/reference/commands/) familiarity from the commands reference.
-This guide explains how to use SpecFact CLI for agile/scrum workflows, including backlog management, sprint planning, dependency tracking, and Definition of Ready (DoR) validation.
-
-Preferred command paths are `specfact backlog ceremony standup ...` and `specfact backlog ceremony refinement ...`. Legacy `backlog daily`/`backlog refine` remain available for compatibility.
-
-Backlog module command surface:
-
-- `specfact backlog add`
-- `specfact backlog analyze-deps`
-- `specfact backlog trace-impact`
-- `specfact backlog verify-readiness`
-- `specfact backlog diff`
-- `specfact backlog sync`
-- `specfact backlog promote`
-- `specfact backlog generate-release-notes`
-- `specfact backlog delta status|impact|cost-estimate|rollback-analysis`
-
-## Backlog Issue Creation (`backlog add`)
-
-Use `specfact backlog add` to create a backlog item with optional parent hierarchy validation and DoR checks.
-
-```bash
-# Non-interactive creation
-specfact backlog add \
- --adapter github \
- --project-id nold-ai/specfact-cli \
- --template github_projects \
- --type story \
- --parent FEAT-123 \
- --title "Implement X" \
- --body "Acceptance criteria: ..." \
- --non-interactive
-
-# Enforce Definition of Ready from .specfact/dor.yaml before create
-specfact backlog add \
- --adapter github \
- --project-id nold-ai/specfact-cli \
- --type story \
- --title "Implement X" \
- --body "Acceptance criteria: ..." \
- --check-dor \
- --repo-path .
-
-# Interactive ADO flow with sprint/iteration selection and story-quality fields
-specfact backlog add \
- --adapter ado \
- --project-id "dominikusnold/Specfact CLI"
-```
-
-Key behavior:
-
-- validates parent exists in current backlog graph before creating
-- validates child-parent type compatibility using `creation_hierarchy` from config/template
-- supports interactive prompts when required fields are missing (unless `--non-interactive`)
-- prompts for ADO sprint/iteration selection and resolves available iterations from `--project-id` context
-- supports multiline body and acceptance criteria capture (default sentinel `::END::`)
-- captures priority and story points for story-like items
-- supports description rendering mode (`markdown` or `classic`)
-- for ADO, supports repeatable `--custom-field key=value` and validates required custom fields / constrained values when mapping metadata exists
-- auto-selects template by adapter when omitted (`ado_scrum` for ADO, `github_projects` for GitHub)
-- creates via adapter protocol (`github` or `ado`) and prints created `id`, `key`, and `url`
-
-## Overview
-
-SpecFact CLI supports real-world agile/scrum practices through:
-
-- **Definition of Ready (DoR)**: Automatic validation of story readiness for sprint planning
-- **Backlog Refinement** 🆕: AI-assisted template-driven refinement for standardizing work items from DevOps backlogs
-- **Daily Standup**: Use `specfact backlog ceremony standup <adapter>` to list my/filtered items with status and last activity.
- Default scope (state=open, limit=20, optional assignee=me) is applied when not overridden; configure via
- `SPECFACT_STANDUP_STATE`, `SPECFACT_STANDUP_LIMIT`, `SPECFACT_STANDUP_ASSIGNEE` or
- `.specfact/standup.yaml`. Use `--iteration` / `--sprint` (e.g. `--sprint current`) to focus on current
- iteration when the adapter supports it; sprint/iteration end date is shown when provided by adapter or
- config (`standup.sprint_end_date`). A second table **Pending / open for commitment** lists unassigned
- items (same scope); use `--show-unassigned`/`--no-show-unassigned` or `--unassigned-only`. Use
- `--blockers-first` to sort items with blockers first; enable `show_priority` or `show_value` in standup
- config for optional priority/value column (value-driven/SAFe). Optional standup summary
- (yesterday/today/blockers) from item body; optionally post standup comment to linked issue via `--post`
- when the adapter supports comments (e.g. GitHub).
- **Interactive step-by-step review**: Use `--interactive` to select stories with arrow keys (questionary)
- and view full detail (refine-like: description, acceptance criteria, standup fields). Interactive detail
- shows the **latest comment only** plus a hint when older comments exist; use export options for full
- comment history. Navigate with Next/Previous/**Post standup update**/Back to list/Exit. `Post standup update`
- posts yesterday/today/blockers to the currently selected story (adapter support required). Use `--suggest-next`
- to show suggested next item by value score (business_value / (story_points × priority)).
- **Copilot export**: Use `--copilot-export <path>` to write a summarized Markdown file of each story for
- Copilot. Add `--comments` (alias `--annotations`) to include descriptions and comment annotations in
- `--copilot-export` and `--summarize` outputs when the adapter supports `get_comments` (GitHub, ADO). All
- summarize/copilot-export content is **normalized to Markdown-only text** (no raw HTML tags or entities)
- so ADO-style HTML fields and Markdown-native fields render consistently. Use `--first-comments N` or
- `--last-comments N` to scope comment volume when needed (default: include all).
- Use `--first-issues N` or `--last-issues N` (mutually exclusive) to scope daily output to oldest/newest
- items by numeric issue/work-item ID.
- **Kanban**: omit iteration/sprint and use state + limit; unassigned = pullable work. **Scrum/SAFe**: use
- `--sprint current` and optional priority/value. **Out of scope**: Sprint goal is in your board/sprint
- settings (not displayed by CLI). Stale/at-risk flags (e.g. "no update in N days") are not in scope—use
- last updated + blockers. Structured "blocked by" (link to another issue) is not in scope; only free-text
- blockers are supported.
-- **Dependency Management**: Track story-to-story and feature-to-feature dependencies
-- **Prioritization**: Priority levels, ranking, and business value scoring
-- **Sprint Planning**: Target sprint/release assignment and story point tracking
-- **Business Value Focus**: User-focused value statements and measurable outcomes
-- **Conflict Resolution**: Persona-aware three-way merge with automatic conflict resolution based on section ownership
-
-## Policy Engine Commands (DoR/DoD/Flow/PI)
-
-Use the readiness and refinement commands to run deterministic readiness checks before sprint and refinement ceremonies:
-
-```bash
-# Validate configured readiness rules against a snapshot
-specfact backlog verify-readiness --repo .
-
-# Generate AI-assisted refinement suggestions (no automatic writes)
-specfact backlog refine --repo .
-```
-
-Policy configuration is loaded from `.specfact/policy.yaml` and supports Scrum (`dor_required_fields`,
-`dod_required_fields`), Kanban column entry/exit requirements, and SAFe PI readiness fields.
-
-**🆕 NEW: Backlog Refinement Integration** - Use `specfact backlog ceremony refinement` to standardize backlog items from GitHub Issues, Azure DevOps, and other tools into template-compliant format before importing into project bundles. See [Backlog Refinement Guide](backlog-refinement.md) for complete documentation.
-
-**Tutorial**: For an end-to-end daily standup and sprint review walkthrough (auto-detect repo, view standup, post comment, interactive, Copilot export), see **[Tutorial: Daily Standup and Sprint Review](../getting-started/tutorial-daily-standup-sprint-review.md)**.
-
-## Daily Standup and Sprint Review
-
-Use **`specfact backlog ceremony standup <adapter>`** to list your standup items (assigned + unassigned) with status and last activity. **By default, GitHub org/repo or Azure DevOps org/project are auto-detected from the git remote** when you run from your cloned repo—no `--repo-owner`/`--repo-name` or `--ado-org`/`--ado-project` needed after authenticating once.
-
-### Auto-Detect from Clone
-
-- **GitHub**: When run from a **GitHub** clone (e.g. `https://github.com/owner/repo` or `git@github.com:owner/repo.git`), SpecFact infers `repo_owner` and `repo_name` from `git remote get-url origin`.
-- **Azure DevOps**: When run from an **ADO** clone (e.g. `https://dev.azure.com/org/project/_git/repo`; SSH keys: `git@ssh.dev.azure.com:v3/org/project/repo`; other SSH: `user@dev.azure.com:v3/org/project/repo`), SpecFact infers `org` and `project` from the remote URL.
-
-Override with `.specfact/backlog.yaml`, environment variables (`SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_ADO_ORG`, etc.), or CLI options when not in the repo or to override. See [Project backlog context](../guides/devops-adapter-integration.md#project-backlog-context-specfactbacklogyaml).
-
-### End-to-End Example: One Standup Session
-
-```bash
-# 1. Authenticate once (if not already)
-specfact backlog auth github
-
-# 2. From repo root: view standup (repo auto-detected)
-cd /path/to/your-repo
-specfact backlog ceremony standup github
-
-# 3. Optional: post standup comment to first item (pass values for yesterday/today/blockers)
-specfact backlog ceremony standup github \
- --yesterday "Worked on X" \
- --today "Will do Y" \
- --blockers "None" \
- --post
-
-# 4. Optional: interactive step-through, Copilot export, or standup summary prompt
-specfact backlog ceremony standup github --interactive # step-through; detail view shows latest comment + hidden-count hint
-# or
-specfact backlog ceremony standup github --copilot-export ./standup.md --comments --last-comments 5
-# or
-specfact backlog ceremony standup github --summarize --comments # prompt to stdout for AI to generate standup summary (Markdown-only)
-specfact backlog ceremony standup github --summarize-to ./standup-prompt.md # plain Markdown file (no HTML/ANSI)
-```
-
-Use the **`specfact.backlog-daily`** (or `specfact.daily`) slash prompt for interactive walkthrough with the
-DevOps team story-by-story (current focus, issues/open questions, discussion notes as comments). Default
-scope: **state=open**, **limit=20**; configure via `SPECFACT_STANDUP_*` or `.specfact/standup.yaml`. Use
-`--assignee me`, `--sprint current`, `--blockers-first`, `--interactive`, `--suggest-next`,
-`--copilot-export <path>`, `--summarize`, `--summarize-to <path>`, `--comments`/`--annotations`, and optional
-`--first-comments`/`--last-comments` plus `--first-issues`/`--last-issues` as well as global filters
-`--search`, `--release`, and `--id` to narrow scope consistently with backlog ceremony refinement.
-The slash prompt itself is provided by the installed backlog bundle rather than the permanent core CLI package.
-See [Tutorial: Daily Standup and Sprint Review](../getting-started/tutorial-daily-standup-sprint-review.md)
-for the full walkthrough.
-
-## Persona-Based Workflows
-
-SpecFact uses persona-based workflows where different roles work on different aspects:
-
-- **Product Owner**: Owns requirements, user stories, business value, prioritization, sprint planning
-- **Architect**: Owns technical constraints, protocols, contracts, architectural decisions, non-functional requirements, risk assessment, deployment architecture
-- **Developer**: Owns implementation tasks, technical design, code mappings, test scenarios, Definition of Done
-
-### Exporting Persona Artifacts
-
-Export persona-specific Markdown files for editing:
-
-```bash
-# Export Product Owner view
-specfact project export --bundle my-project --persona product-owner
-
-# Export Developer view
-specfact project export --bundle my-project --persona developer
-
-# Export Architect view
-specfact project export --bundle my-project --persona architect
-
-# Export to custom location
-specfact project export --bundle my-project --persona product-owner --output docs/backlog.md
-```
-
-The exported Markdown includes persona-specific content:
-
-**Product Owner Export**:
-
-- **Definition of Ready Checklist**: Visual indicators for each DoR criterion
-- **Prioritization Data**: Priority, rank, business value scores
-- **Dependencies**: Clear dependency chains (depends on, blocks)
-- **Business Value**: User-focused value statements and metrics
-- **Sprint Planning**: Target dates, sprints, and releases
-
-**Developer Export**:
-
-- **Acceptance Criteria**: Feature and story acceptance criteria
-- **User Stories**: Detailed story context with tasks, contracts, scenarios
-- **Implementation Tasks**: Granular tasks with file paths
-- **Code Mappings**: Source and test function mappings
-- **Sprint Context**: Story points, priority, dependencies, target sprint/release
-- **Definition of Done**: Completion criteria checklist
-
-**Architect Export**:
-
-- **Technical Constraints**: Feature-level technical constraints
-- **Architectural Decisions**: Technology choices, patterns, integration approaches
-- **Non-Functional Requirements**: Performance, scalability, availability, security, reliability targets
-- **Protocols & State Machines**: Complete protocol definitions with states and transitions
-- **Contracts**: OpenAPI/AsyncAPI contract details
-- **Risk Assessment**: Technical risks and mitigation strategies
-- **Deployment Architecture**: Infrastructure and deployment patterns
-
-### Importing Persona Edits
-
-After editing the Markdown file, import changes back:
-
-```bash
-# Import Product Owner edits
-specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
-
-# Import Developer edits
-specfact project import --bundle my-project --persona developer --source docs/developer.md
-
-# Import Architect edits
-specfact project import --bundle my-project --persona architect --source docs/architect.md
-
-# Dry-run to validate without applying
-specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
-```
-
-The import process validates:
-
-- **Template Structure**: Required sections present
-- **DoR Completeness**: All DoR criteria met
-- **Dependency Integrity**: No circular dependencies, all references exist
-- **Priority Consistency**: Valid priority formats (P0-P3, MoSCoW)
-- **Date Formats**: ISO 8601 date validation
-- **Story Point Ranges**: Valid Fibonacci-like values
-
-## Section Locking
-
-SpecFact supports section-level locking to prevent concurrent edits and ensure data integrity when multiple personas work on the same project bundle.
-
-### Lock Workflow
-
-#### Step 1: Lock Section Before Editing
-
-Lock the sections you plan to edit to prevent conflicts:
-
-```bash
-# Product Owner locks idea section
-specfact project lock --bundle my-project --section idea --persona product-owner
-
-# Architect locks protocols section
-specfact project lock --bundle my-project --section protocols --persona architect
-```
-
-#### Step 2: Export and Edit
-
-Export your persona view, make edits, then import back:
-
-```bash
-# Export
-specfact project export --bundle my-project --persona product-owner
-
-# Edit the exported Markdown file
-# ... make your changes ...
-
-# Import (will be blocked if section is locked by another persona)
-specfact project import --bundle my-project --persona product-owner --input product-owner.md
-```
-
-#### Step 3: Unlock After Completing Edits
-
-Unlock the section when you're done:
-
-```bash
-# Unlock section
-specfact project unlock --bundle my-project --section idea
-```
-
-### Lock Enforcement
-
-The `project import` command automatically checks locks before saving:
-
-- **Allowed**: Import succeeds if you own the locked section
-- **Blocked**: Import fails if section is locked by another persona
-- **Blocked**: Import fails if section is locked and you don't own it
-
-#### Example: Lock Enforcement in Action
-
-```bash
-# Product Owner locks idea section
-specfact project lock --bundle my-project --section idea --persona product-owner
-
-# Product Owner imports (succeeds - owns the section)
-specfact project import --bundle my-project --persona product-owner --input backlog.md
-# ✓ Import successful
-
-# Architect tries to import (fails - section is locked)
-specfact project import --bundle my-project --persona architect --input architect.md
-# ✗ Error: Cannot import: Section(s) are locked
-# - Section 'idea' is locked by 'product-owner' (locked at 2025-12-12T10:00:00Z)
-```
-
-### Real-World Workflow Example
-
-**Scenario**: Product Owner and Architect working in parallel
-
-```bash
-# Morning: Product Owner locks idea and business sections
-specfact project lock --bundle my-project --section idea --persona product-owner
-specfact project lock --bundle my-project --section business --persona product-owner
-
-# Product Owner exports and edits
-specfact project export --bundle my-project --persona product-owner
-# Edit docs/project-plans/my-project/product-owner.md
-
-# Product Owner imports (succeeds)
-specfact project import --bundle my-project --persona product-owner \
- --input docs/project-plans/my-project/product-owner.md
-
-# Product Owner unlocks after completing edits
-specfact project unlock --bundle my-project --section idea
-specfact project unlock --bundle my-project --section business
-
-# Afternoon: Architect locks protocols section
-specfact project lock --bundle my-project --section protocols --persona architect
-
-# Architect exports and edits
-specfact project export --bundle my-project --persona architect
-# Edit docs/project-plans/my-project/architect.md
-
-# Architect imports (succeeds)
-specfact project import --bundle my-project --persona architect \
- --input docs/project-plans/my-project/architect.md
-
-# Architect unlocks
-specfact project unlock --bundle my-project --section protocols
-```
-
-### Checking Locks
-
-List all current locks:
-
-```bash
-# List all locks
-specfact project locks --bundle my-project
-```
-
-**Output:**
-
-```text
-Section Locks
-┌─────────────────────┬──────────────────┬─────────────────────────┬──────────────────┐
-│ Section │ Owner │ Locked At │ Locked By │
-├─────────────────────┼──────────────────┼─────────────────────────┼──────────────────┤
-│ idea │ product-owner │ 2025-12-12T10:00:00Z │ user@hostname │
-│ protocols │ architect │ 2025-12-12T14:00:00Z │ user@hostname │
-└─────────────────────┴──────────────────┴─────────────────────────┴──────────────────┘
-```
-
-### Lock Best Practices
-
-1. **Lock Before Editing**: Always lock sections before exporting and editing
-2. **Unlock Promptly**: Unlock sections immediately after completing edits
-3. **Check Locks First**: Use `project locks` to see what's locked before starting work
-4. **Coordinate with Team**: Communicate lock usage to avoid blocking teammates
-5. **Use Granular Locks**: Lock only the sections you need, not entire bundles
-
-### Troubleshooting Locks
-
-**Issue**: Import fails with "Section(s) are locked"
-
-**Solution**: Check who locked the section and coordinate:
-
-```bash
-# Check locks
-specfact project locks --bundle my-project
-
-# Contact the lock owner or wait for them to unlock
-# Or ask them to unlock: specfact project unlock --section <section>
-```
-
-**Issue**: Can't lock section - "already locked"
-
-**Solution**: Someone else has locked it. Check locks and coordinate:
-
-```bash
-# See who locked it
-specfact project locks --bundle my-project
-
-# Wait for unlock or coordinate with lock owner
-```
-
-**Issue**: Locked section but forgot to unlock
-
-**Solution**: Unlock manually:
-
-```bash
-# Unlock the section
-specfact project unlock --bundle my-project --section <section>
-```
-
-## Conflict Resolution
-
-When multiple personas work on the same project bundle in parallel, conflicts can occur when merging changes. SpecFact provides persona-aware conflict resolution that automatically resolves conflicts based on section ownership.
-
-### How Persona-Based Conflict Resolution Works
-
-SpecFact uses a three-way merge algorithm that:
-
-1. **Detects conflicts**: Compares base (common ancestor), ours (current branch), and theirs (incoming branch) versions
-2. **Checks ownership**: Determines which persona owns each conflicting section based on bundle manifest
-3. **Auto-resolves**: Automatically resolves conflicts when ownership is clear:
- - If only one persona owns the section → that persona's version wins
- - If both personas own it and they're the same → current branch wins
- - If both personas own it and they're different → requires manual resolution
-4. **Interactive resolution**: Prompts for manual resolution when ownership is ambiguous
-
-### Merge Workflow
-
-**Step 1: Export and Edit**
-
-Each persona exports their view, edits it, and imports back:
-
-```bash
-# Product Owner exports and edits
-specfact project export --bundle my-project --persona product-owner
-# Edit docs/project-plans/my-project/product-owner.md
-specfact project import --bundle my-project --persona product-owner --source docs/project-plans/my-project/product-owner.md
-
-# Architect exports and edits (in parallel)
-specfact project export --bundle my-project --persona architect
-# Edit docs/project-plans/my-project/architect.md
-specfact project import --bundle my-project --persona architect --source docs/project-plans/my-project/architect.md
-```
-
-**Step 2: Merge Changes**
-
-When merging branches, use `project merge` with persona information:
-
-```bash
-# Merge with automatic persona-based resolution
-specfact project merge \
- --bundle my-project \
- --base main \
- --ours po-branch \
- --theirs arch-branch \
- --persona-ours product-owner \
- --persona-theirs architect
-```
-
-**Step 3: Resolve Remaining Conflicts**
-
-If conflicts remain after automatic resolution, resolve them interactively:
-
-```bash
-# The merge command will prompt for each unresolved conflict:
-# Choose resolution: [ours/theirs/base/manual]
-```
-
-Or resolve individual conflicts manually:
-
-```bash
-# Resolve a specific conflict
-specfact project resolve-conflict \
- --bundle my-project \
- --path features.FEATURE-001.title \
- --resolution ours
-```
-
-### Example: Resolving a Conflict
-
-**Scenario**: Product Owner and Architect both modified the same feature title.
-
-**Base version** (common ancestor):
-
-```yaml
-features:
- FEATURE-001:
- title: "User Authentication"
-```
-
-**Product Owner's version** (ours):
-
-```yaml
-features:
- FEATURE-001:
- title: "Secure User Authentication"
-```
-
-**Architect's version** (theirs):
-
-```yaml
-features:
- FEATURE-001:
- title: "OAuth2 User Authentication"
-```
-
-**Automatic Resolution**:
-
-1. SpecFact checks ownership: `features.FEATURE-001` is owned by `product-owner` (based on manifest)
-2. Since Product Owner owns this section, their version wins automatically
-3. Result: `"Secure User Authentication"` is kept
-
-**Manual Resolution** (if both personas own it):
-
-If both personas own the section, SpecFact prompts:
-
-```
-Resolving conflict: features.FEATURE-001.title
-Base: User Authentication
-Ours (product-owner): Secure User Authentication
-Theirs (architect): OAuth2 User Authentication
-
-Choose resolution [ours/theirs/base/manual]: manual
-Enter manual value: OAuth2 Secure User Authentication
-```
-
-### Conflict Resolution Strategies
-
-You can specify a merge strategy to override automatic resolution:
-
-- **`auto`** (default): Persona-based automatic resolution
-- **`ours`**: Always prefer our version
-- **`theirs`**: Always prefer their version
-- **`base`**: Always prefer base version
-- **`manual`**: Require manual resolution for all conflicts
-
-```bash
-# Use manual strategy for full control
-specfact project merge \
- --bundle my-project \
- --base main \
- --ours po-branch \
- --theirs arch-branch \
- --persona-ours product-owner \
- --persona-theirs architect \
- --strategy manual
-```
-
-### CI/CD Integration
-
-For automated workflows, use `--no-interactive`:
-
-```bash
-# Non-interactive merge (fails if conflicts require manual resolution)
-specfact project merge \
- --bundle my-project \
- --base main \
- --ours HEAD \
- --theirs origin/feature \
- --persona-ours product-owner \
- --persona-theirs architect \
- --no-interactive
-```
-
-**Note**: In non-interactive mode, the merge will fail if there are conflicts that require manual resolution. Use this in CI/CD pipelines only when you're confident conflicts will be auto-resolved.
-
-### Best Practices
-
-1. **Set Clear Ownership**: Ensure persona ownership is clearly defined in bundle manifest
-2. **Merge Frequently**: Merge branches frequently to reduce conflict scope
-3. **Review Auto-Resolutions**: Review automatically resolved conflicts before committing
-4. **Use Manual Strategy for Complex Conflicts**: When in doubt, use `--strategy manual` for full control
-5. **Document Resolution Decisions**: Add comments explaining why certain resolutions were chosen
-
-### Troubleshooting Conflicts
-
-**Issue**: Merge fails with "unresolved conflicts"
-
-**Solution**: Use interactive mode to resolve conflicts:
-
-```bash
-# Run merge in interactive mode
-specfact project merge \
- --bundle my-project \
- --base main \
- --ours po-branch \
- --theirs arch-branch \
- --persona-ours product-owner \
- --persona-theirs architect
-# Follow prompts to resolve each conflict
-```
-
-**Issue**: Auto-resolution chose wrong version
-
-**Solution**: Check persona ownership in manifest, or use manual strategy:
-
-```bash
-# Check ownership
-specfact project export --bundle my-project --list-personas
-
-# Use manual strategy
-specfact project merge --strategy manual ...
-```
-
-**Issue**: Conflict path not found
-
-**Solution**: Use correct conflict path format:
-
-- `idea.title` - Idea title
-- `business.value_proposition` - Business value proposition
-- `features.FEATURE-001.title` - Feature title
-- `features.FEATURE-001.stories.STORY-001.description` - Story description
-
-## Definition of Ready (DoR)
-
-### DoR Validation in Backlog Refinement 🆕
-
-When refining backlog items from DevOps tools, you can validate DoR rules before refinement:
-
-```bash
-# Check DoR before refining backlog items
-specfact backlog ceremony refinement github --check-dor --labels feature
-
-# DoR configuration in .specfact/dor.yaml
-rules:
- story_points: true
- priority: true
- business_value: true
- acceptance_criteria: true
- dependencies: false # Optional
-```
-
-**See**: [Backlog Refinement Guide](backlog-refinement.md#definition-of-ready-dor) for DoR validation in backlog refinement workflow.
-
-### DoR Checklist
-
-Each story must meet these criteria before sprint planning:
-
-- [x] **Story Points**: Complexity estimated (1, 2, 3, 5, 8, 13, 21...)
-- [x] **Value Points**: Business value estimated (1, 2, 3, 5, 8, 13, 21...)
-- [x] **Priority**: Priority level set (P0-P3 or MoSCoW)
-- [x] **Dependencies**: Dependencies identified and validated
-- [x] **Business Value**: Clear business value description present
-- [x] **Target Date**: Target completion date set (optional but recommended)
-- [x] **Target Sprint**: Target sprint assigned (optional but recommended)
-
-### Example: Story with Complete DoR
-
-```markdown
-**Story 1**: User can login with email
-
-**Definition of Ready**:
-- [x] Story Points: 5 (Complexity)
-- [x] Value Points: 8 (Business Value)
-- [x] Priority: P1
-- [x] Dependencies: 1 identified
-- [x] Business Value: ✓
-- [x] Target Date: 2025-01-15
-- [x] Target Sprint: Sprint 2025-01
-
-**Story Details**:
-- **Story Points**: 5 (Complexity)
-- **Value Points**: 8 (Business Value)
-- **Priority**: P1
-- **Rank**: 1
-- **Target Date**: 2025-01-15
-- **Target Sprint**: Sprint 2025-01
-- **Target Release**: v2.1.0
-
-**Business Value**:
-Enables users to securely access their accounts, reducing support tickets by 30% and improving user satisfaction.
-
-**Business Metrics**:
-- Reduce support tickets by 30%
-- Increase user login success rate to 99.5%
-- Reduce password reset requests by 25%
-
-**Dependencies**:
-**Depends On**:
-- STORY-000: User registration system
-
-**Acceptance Criteria** (User-Focused):
-- [ ] As a user, I can enter my email and password to log in
-- [ ] As a user, I receive clear error messages if login fails
-- [ ] As a user, I am redirected to my dashboard after successful login
-```
-
-## Dependency Management
-
-### Story Dependencies
-
-Track dependencies between stories:
-
-```markdown
-**Dependencies**:
-**Depends On**:
-- STORY-001: User registration system
-- STORY-002: Email verification
-
-**Blocks**:
-- STORY-010: Password reset flow
-```
-
-### Feature Dependencies
-
-Track dependencies between features:
-
-```markdown
-### FEATURE-001: User Authentication
-
-#### Dependencies
-
-**Depends On Features**:
-- FEATURE-000: User Management Infrastructure
-
-**Blocks Features**:
-- FEATURE-002: User Profile Management
-```
-
-### Validation Rules
-
-The import process validates:
-
-1. **Reference Existence**: All referenced stories/features exist
-2. **No Circular Dependencies**: Prevents A → B → A cycles
-3. **Format Validation**: Dependency keys match expected format (STORY-001, FEATURE-001)
-
-### Example: Circular Dependency Error
-
-```bash
-$ specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-Error: Agile/Scrum validation failed:
- - Story STORY-001: Circular dependency detected with 'STORY-002'
- - Feature FEATURE-001: Circular dependency detected with 'FEATURE-002'
-```
-
-## Prioritization
-
-### Priority Levels
-
-Use one of these priority formats:
-
-- **P0-P3**: P0=Critical, P1=High, P2=Medium, P3=Low
-- **MoSCoW**: Must, Should, Could, Won't
-- **Descriptive**: Critical, High, Medium, Low
-
-### Ranking
-
-Use backlog rank (1 = highest priority):
-
-```markdown
-**Priority**: P1 | **Rank**: 1
-```
-
-### Business Value Scoring
-
-Score features 0-100 for business value:
-
-```markdown
-**Business Value Score**: 75/100
-```
-
-### Example: Prioritized Feature
-
-```markdown
-### FEATURE-001: User Authentication
-
-**Priority**: P1 | **Rank**: 1
-**Business Value Score**: 75/100
-**Target Release**: v2.1.0
-**Estimated Story Points**: 13
-
-#### Business Value
-
-Enables secure user access, reducing support overhead and improving user experience.
-
-**Target Users**: end-user, admin
-
-**Success Metrics**:
-- Reduce support tickets by 30%
-- Increase user login success rate to 99.5%
-- Reduce password reset requests by 25%
-```
-
-## Sprint Planning
-
-### Story Point Estimation
-
-Use Fibonacci-like values: 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 100
-
-```markdown
-- **Story Points**: 5 (Complexity)
-- **Value Points**: 8 (Business Value)
-```
-
-### Backlog Refinement Before Sprint Planning 🆕
-
-Before sprint planning, refine backlog items from DevOps tools (GitHub Issues, Azure DevOps) into structured, template-compliant format:
-
-```bash
-# Refine GitHub issues in current sprint
-specfact backlog ceremony refinement github --sprint "Sprint 1" --check-dor --labels feature
-
-# Refine ADO work items with DoR validation
-specfact backlog ceremony refinement ado --iteration "Project\\Sprint 1" --check-dor --state Active
-
-# Use persona/framework filtering for role-specific templates
-specfact backlog ceremony refinement github --persona product-owner --framework scrum --sprint "Sprint 1"
-```
-
-**Benefits**:
-
-- Standardizes unstructured backlog input into corporate templates
-- Validates DoR before adding items to sprints
-- Filters by sprint, release, iteration for agile workflows
-- Preserves original backlog data for round-trip synchronization
-
-**See**: [Backlog Refinement Guide](backlog-refinement.md) for complete documentation.
-
-### Target Sprint Assignment
-
-Assign stories to specific sprints:
-
-```markdown
-- **Target Sprint**: Sprint 2025-01
-- **Target Release**: v2.1.0
-- **Target Date**: 2025-01-15
-```
-
-### Feature-Level Totals
-
-Feature story point totals are automatically calculated:
-
-```markdown
-**Estimated Story Points**: 13
-```
-
-This is the sum of all story points for stories in this feature.
-
-## Business Value Focus
-
-### User-Focused Value Statements
-
-Write stories with clear user value:
-
-```markdown
-**Business Value**:
-As a user, I want to securely log in to my account so that I can access my personalized dashboard and manage my data.
-
-**Business Metrics**:
-- Reduce support tickets by 30%
-- Increase user login success rate to 99.5%
-- Reduce password reset requests by 25%
-```
-
-### Acceptance Criteria Format
-
-Use "As a [user], I want [capability] so that [outcome]" format:
-
-```markdown
-**Acceptance Criteria** (User-Focused):
-- [ ] As a user, I can enter my email and password to log in
-- [ ] As a user, I receive clear error messages if login fails
-- [ ] As a user, I am redirected to my dashboard after successful login
-```
-
-## Template Customization
-
-### Override Default Templates
-
-Create project-specific templates in `.specfact/templates/persona/`:
-
-```bash
-.specfact/
-└── templates/
- └── persona/
- └── product-owner.md.j2 # Project-specific template
-```
-
-The project-specific template overrides the default template in `resources/templates/persona/`.
-
-### Template Structure
-
-Templates use Jinja2 syntax with these variables:
-
-- `bundle_name`: Project bundle name
-- `features`: Dictionary of features (key -> feature dict)
-- `idea`: Idea section data
-- `business`: Business section data
-- `locks`: Section locks information
-
-### Example: Custom Template Section
-
-```jinja2
-{% raw %}{% if features %}
-## Features & User Stories
-
-{% for feature_key, feature in features.items() %}
-### {{ feature.key }}: {{ feature.title }}
-
-**Priority**: {{ feature.priority | default('Not Set') }}
-**Business Value**: {{ feature.business_value_score | default('Not Set') }}/100
-
-{% if feature.stories %}
-#### User Stories
-
-{% for story in feature.stories %}
-**Story {{ loop.index }}**: {{ story.title }}
-
-**DoR Status**: {{ '✓ Complete' if story.definition_of_ready.values() | all else '✗ Incomplete' }}
-
-{% endfor %}
-{% endif %}
-
-{% endfor %}
-{% endif %}{% endraw %}
-```
-
-## Validation Examples
-
-### DoR Validation
-
-```bash
-$ specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-Error: Agile/Scrum validation failed:
- - Story STORY-001 (Feature FEATURE-001): Missing story points (required for DoR)
- - Story STORY-001 (Feature FEATURE-001): Missing value points (required for DoR)
- - Story STORY-001 (Feature FEATURE-001): Missing priority (required for DoR)
- - Story STORY-001 (Feature FEATURE-001): Missing business value description (required for DoR)
-```
-
-### Dependency Validation
-
-```bash
-$ specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-Error: Agile/Scrum validation failed:
- - Story STORY-001: Dependency 'STORY-999' does not exist
- - Story STORY-001: Circular dependency detected with 'STORY-002'
- - Feature FEATURE-001: Dependency 'FEATURE-999' does not exist
-```
-
-### Priority Validation
-
-```bash
-$ specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-Error: Agile/Scrum validation failed:
- - Story STORY-001: Invalid priority 'P5' (must be P0-P3, MoSCoW, or Critical/High/Medium/Low)
- - Feature FEATURE-001: Invalid priority 'Invalid' (must be P0-P3, MoSCoW, or Critical/High/Medium/Low)
-```
-
-### Date Format Validation
-
-```bash
-$ specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-Error: Agile/Scrum validation failed:
- - Story STORY-001: Invalid date format '2025/01/15' (expected ISO 8601: YYYY-MM-DD)
- - Story STORY-001: Warning - target date '2024-01-15' is in the past (may need updating)
-```
-
-## Best Practices
-
-### 1. Complete DoR Before Sprint Planning
-
-Ensure all stories meet DoR criteria before assigning to sprints:
-
-```bash
-# Validate DoR completeness
-specfact project import --bundle my-project --persona product-owner --source backlog.md --dry-run
-```
-
-### 2. Track Dependencies Early
-
-Identify dependencies during story creation to avoid blockers:
-
-```markdown
-**Dependencies**:
-**Depends On**:
-- STORY-001: User registration (must complete first)
-```
-
-### 3. Use Consistent Priority Formats
-
-Choose one priority format per project and use consistently:
-
-- **Option 1**: P0-P3 (recommended for technical teams)
-- **Option 2**: MoSCoW (recommended for business-focused teams)
-- **Option 3**: Descriptive (Critical/High/Medium/Low)
-
-### 4. Set Business Value for All Stories
-
-Every story should have a clear business value statement:
-
-```markdown
-**Business Value**:
-Enables users to securely access their accounts, reducing support tickets by 30%.
-```
-
-### 5. Use Story Points for Capacity Planning
-
-Track story points to estimate sprint capacity:
-
-```markdown
-**Estimated Story Points**: 21 # Sum of all stories in feature
-```
-
-## Troubleshooting
-
-### Validation Errors
-
-If import fails with validation errors:
-
-1. **Check DoR Completeness**: Ensure all required fields are present
-2. **Verify Dependencies**: Check that all referenced stories/features exist
-3. **Validate Formats**: Ensure priority, dates, and story points use correct formats
-4. **Review Business Value**: Ensure business value descriptions are present and meaningful
-
-### Template Issues
-
-If template rendering fails:
-
-1. **Check Template Syntax**: Verify Jinja2 syntax is correct
-2. **Verify Variables**: Ensure template variables match exported data structure
-3. **Test Template**: Use `--dry-run` to test template without importing
-
-## Related Documentation
-
-- [Command Reference - Project Commands](../reference/commands.md#project---project-bundle-management) - Complete command documentation including `project merge` and `project resolve-conflict`
-- [Project Bundle Structure](../reference/directory-structure.md) - Project bundle organization
-- See [Project Commands](../reference/commands.md#project---project-bundle-management) for template customization options
+**Full guide on the canonical modules docs site:** [Agile and Scrum workflows](https://modules.specfact.io/guides/agile-scrum-workflows/)
diff --git a/docs/guides/backlog-delta-commands.md b/docs/guides/backlog-delta-commands.md
index 3cabe09c..534bec61 100644
--- a/docs/guides/backlog-delta-commands.md
+++ b/docs/guides/backlog-delta-commands.md
@@ -2,39 +2,13 @@
layout: default
title: Backlog Delta Commands
permalink: /guides/backlog-delta-commands/
+description: Handoff to backlog delta commands on the modules documentation site.
---
-# Backlog Delta Commands
+# Backlog delta commands
+Delta commands help you inspect and reason about changes between backlog states—status, impact, cost, and rollback views. Syntax, options, and examples are documented with the backlog bundle on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Commands reference](https://docs.specfact.io/reference/commands/) for base CLI; backlog bundle installed for delta subcommands.
-`delta` commands are grouped under backlog because they describe backlog graph drift and impact, not source-code diffs.
-
-## Command Group
-
-```bash
-specfact backlog delta status --project-id <id> --adapter <github|ado>
-specfact backlog delta impact <item-id> --project-id <id> --adapter <github|ado>
-specfact backlog delta cost-estimate --project-id <id> --adapter <github|ado>
-specfact backlog delta rollback-analysis --project-id <id> --adapter <github|ado>
-```
-
-## What Each Command Does
-
-- `status`: compares current graph vs baseline and summarizes added/updated/deleted nodes and edges.
-- `impact`: traces downstream effects for a changed item.
-- `cost-estimate`: estimates effort from detected delta scope.
-- `rollback-analysis`: identifies likely breakage if recent delta is reverted.
-
-## Baseline
-
-`status`, `cost-estimate`, and `rollback-analysis` rely on a backlog baseline graph (default `.specfact/backlog-baseline.json`).
-
-Generate/update baseline with:
-
-```bash
-specfact project snapshot --bundle <bundle>
-```
+**Full guide on the canonical modules docs site:** [Backlog delta](https://modules.specfact.io/bundles/backlog/delta/)
diff --git a/docs/guides/backlog-dependency-analysis.md b/docs/guides/backlog-dependency-analysis.md
index 86e03b6b..fa161127 100644
--- a/docs/guides/backlog-dependency-analysis.md
+++ b/docs/guides/backlog-dependency-analysis.md
@@ -2,43 +2,13 @@
layout: default
title: Backlog Dependency Analysis
permalink: /guides/backlog-dependency-analysis/
+description: Handoff to backlog dependency analysis on the modules documentation site.
---
-# Backlog Dependency Analysis
+# Backlog dependency analysis
+This guide explains how to analyze dependencies between backlog items—ordering, blockers, and cross-team impact—using SpecFact backlog tooling. Detailed procedures and command output interpretation live on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** Project linked to a backlog; see [Getting started](https://docs.specfact.io/getting-started/quickstart/) if you are new to SpecFact.
-Use SpecFact to build a provider-agnostic dependency graph from backlog tools and analyze execution risk before delivery.
-
-## Commands
-
-```bash
-specfact backlog analyze-deps --project-id <id> --adapter <github|ado> --template <template>
-specfact backlog trace-impact <item-id> --project-id <id> --adapter <github|ado>
-specfact backlog verify-readiness --project-id <id> --adapter <github|ado>
-specfact backlog export-roadmap --project-id <id> --adapter <github|ado> # via project command: see devops flow guide
-```
-
-## Typical Flow
-
-1. Run `analyze-deps` to compute typed coverage, orphans, cycles, and critical path.
-2. Run `trace-impact` for candidate changes to estimate downstream blast radius.
-3. Run `verify-readiness` before release for blocker and child-completion checks.
-
-## Templates
-
-- `github_projects`
-- `ado_scrum`
-- `ado_safe`
-- `jira_kanban`
-
-Use `--template` to align type/dependency rules with your backlog model.
-
-## Outputs
-
-- Rich terminal summary (coverage/cycle/orphan metrics).
-- Optional graph JSON export from `analyze-deps` via `--json-export`.
-- Optional markdown report from `analyze-deps` via `--output`.
+**Full guide on the canonical modules docs site:** [Backlog dependency analysis](https://modules.specfact.io/bundles/backlog/dependency-analysis/)
diff --git a/docs/guides/backlog-refinement.md b/docs/guides/backlog-refinement.md
index d99ddaac..740aa8bb 100644
--- a/docs/guides/backlog-refinement.md
+++ b/docs/guides/backlog-refinement.md
@@ -2,1076 +2,13 @@
layout: default
title: Backlog Refinement Guide
permalink: /guides/backlog-refinement/
+description: Handoff to backlog refinement workflows on the canonical modules docs site.
---
-# Backlog Refinement Guide
+# Backlog refinement
+Backlog refinement covers interactive and scripted refinement of work items—quality bars, templates, adapters, and writeback behavior. Command references and deep workflows are owned by the backlog bundles on the modules documentation site.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** Backlog-related modules installed or available as bundled; tracker credentials configured per [Authentication](https://docs.specfact.io/reference/authentication/) if you use live trackers.
-> **🆕 NEW FEATURE: AI-Assisted Template-Driven Backlog Refinement**
-> Transform arbitrary DevOps backlog input into structured, template-compliant work items using AI-assisted refinement with template detection and validation.
-
-This guide explains how to use SpecFact CLI's backlog refinement feature to standardize work items from GitHub Issues, Azure DevOps, and other backlog tools into corporate templates (user stories, defects, spikes, enablers).
-
-Preferred command path is `specfact backlog ceremony refinement ...`. The legacy `specfact backlog refine ...` path remains supported for compatibility.
-
-**Tutorial**: For an end-to-end walkthrough with your AI IDE (Cursor, VS Code, etc.)—including interactive slash prompt, story quality, underspecification, splitting, and DoR—see **[Tutorial: Backlog Refine with AI IDE](../getting-started/tutorial-backlog-refine-ai-ide.md)**.
-
-## Overview
-
-**Why This Matters**: DevOps teams often create backlog items with informal, unstructured descriptions. Template-driven refinement helps enforce corporate standards while maintaining lossless synchronization with your backlog tools.
-
-SpecFact CLI's backlog refinement feature:
-
-- **Template Detection**: Automatically detects which template (user story, defect, spike, enabler) matches a backlog item
-- **AI-Assisted Refinement**: Generates prompts for IDE AI copilots to refine unstructured input into template-compliant format
-- **Confidence Scoring**: Validates refined content and provides confidence scores
-- **Lossless Preservation**: Preserves original backlog data for round-trip synchronization
-- **Arbitrary Input Handling**: Works with any DevOps backlog format (GitHub Issues, ADO work items, etc.)
-
-**Architecture Note**: SpecFact CLI follows a CLI-first architecture:
-
-- SpecFact CLI generates prompts/instructions for IDE AI copilots (Cursor, Claude Code, etc.)
-- IDE AI copilots execute those instructions using their native LLM
-- IDE AI copilots feed results back to SpecFact CLI
-- SpecFact CLI validates and processes the results
-- SpecFact CLI does NOT directly invoke LLM APIs (OpenAI, Anthropic, etc.)
-
----
-
-## Quick Start
-
-### 1. Refine a Single Backlog Item
-
-```bash
-# Refine GitHub issues (auto-detect template)
-specfact backlog ceremony refinement github --search "is:open label:feature"
-
-# Filter by labels and state
-specfact backlog ceremony refinement github --labels feature,enhancement --state open
-
-# Filter by sprint and assignee
-specfact backlog ceremony refinement github --sprint "Sprint 1" --assignee dev1
-
-# Filter by framework and persona (Scrum + Product Owner)
-specfact backlog ceremony refinement github --framework scrum --persona product-owner --labels feature
-
-# Refine with specific template
-specfact backlog ceremony refinement github --template user_story_v1 --search "is:open"
-
-# Check Definition of Ready before refinement
-specfact backlog ceremony refinement github --check-dor --labels feature
-
-# Preview refinement without writing (default - safe mode)
-specfact backlog ceremony refinement github --preview --labels feature
-
-# Write refinement to backlog (explicit opt-in required)
-specfact backlog ceremony refinement github --write --labels feature
-
-# Auto-accept high-confidence refinements
-specfact backlog ceremony refinement github --auto-accept-high-confidence --search "is:open"
-```
-
-### 2. Refine and Import to OpenSpec Bundle
-
-```bash
-# Refine and automatically import to OpenSpec bundle
-specfact backlog ceremony refinement github \
- --bundle my-project \
- --auto-bundle \
- --search "is:open label:enhancement"
-```
-
-### 3. Refine Azure DevOps Work Items
-
-```bash
-# Refine ADO work items
-specfact backlog ceremony refinement ado --search "State = 'New'"
-
-# Filter by sprint and state
-specfact backlog ceremony refinement ado --sprint "Sprint 1" --state Active
-
-# Filter by iteration path (ADO format)
-specfact backlog ceremony refinement ado --iteration "Project\\Release 1\\Sprint 1"
-
-# Refine with defect template
-specfact backlog ceremony refinement ado --template defect_v1 --search "WorkItemType = 'Bug'"
-
-# Use custom field mapping for custom ADO process templates
-specfact backlog ceremony refinement ado \
- --ado-org my-org \
- --ado-project my-project \
- --custom-field-mapping /path/to/ado_custom.yaml \
- --state Active
-```
-
----
-
-## How It Works
-
-### Step 1: Fetch Backlog Items
-
-The command fetches backlog items from the specified adapter (GitHub, ADO, etc.) and converts them to the unified `BacklogItem` domain model.
-
-```bash
-specfact backlog ceremony refinement github --search "is:open"
-```
-
-**Note**: Adapter search methods (`adapter.search_issues()`, `adapter.list_work_items()`) are required for fetching. These will be implemented when adapters support them.
-
-### Step 2: Template Detection with Priority-Based Resolution
-
-For each backlog item, SpecFact CLI detects which template best matches using **priority-based resolution**:
-
-- **Priority Order** (most specific to least specific):
- 1. `provider+framework+persona` (e.g., GitHub + Scrum + Product Owner)
- 2. `provider+framework` (e.g., GitHub + Scrum)
- 3. `framework+persona` (e.g., Scrum + Product Owner)
- 4. `framework` (e.g., Scrum)
- 5. `provider+persona` (e.g., GitHub + Product Owner)
- 6. `persona` (e.g., Product Owner)
- 7. `provider` (e.g., GitHub)
- 8. Default (framework-agnostic, persona-agnostic, provider-agnostic)
-
-- **Detection Scoring**:
- - **Structural Fit** (60% weight): Checks if required section headings are present
- - **Pattern Fit** (40% weight): Matches regex patterns in title and body
- - **Confidence Score**: Calculates weighted confidence (0.0-1.0)
- - **Missing Fields**: Identifies required template fields that are missing
-
-```bash
-# Auto-detect template with persona/framework filtering (default)
-specfact backlog ceremony refinement github --framework scrum --persona product-owner --search "is:open"
-
-# Force specific template (overrides priority-based resolution)
-specfact backlog ceremony refinement github --template user_story_v1 --search "is:open"
-```
-
-### Step 3: AI-Assisted Refinement
-
-SpecFact CLI generates a refinement prompt for your IDE AI copilot:
-
-1. **Prompt Generation**: Creates a markdown prompt with:
- - Original backlog item content
- - Target template structure
- - Required sections and fields
- - Examples and guidelines
-
-2. **IDE AI Copilot Execution**: You copy the prompt to your IDE AI copilot (Cursor, Claude Code, etc.), which:
- - Executes the refinement using its native LLM
- - Returns refined content in template-compliant format
-
-3. **Validation**: SpecFact CLI validates the refined content:
- - Checks for required sections
- - Detects TODO markers (reduces confidence)
- - Detects NOTES sections (reduces confidence)
- - Calculates confidence score (0.0-1.0)
-
-```bash
-# Interactive refinement (default)
-specfact backlog ceremony refinement github --search "is:open"
-
-# The CLI will:
-# 1. Display the refinement prompt
-# 2. Wait for you to paste refined content from IDE AI copilot
-# 3. Validate and score the refinement
-# 4. Ask for confirmation before applying
-```
-
-### Story scope and specification level
-
-During interactive refinement (e.g. when using the slash prompt in your AI IDE), the team should assess each story’s **specification level** so you can improve quality and respect Definition of Ready:
-
-- **Under-specified**: Missing acceptance criteria, vague scope, unclear “so that” or user value. The AI should list what’s missing (e.g. “No AC”, “Scope could mean X or Y”) so the team can add detail before approving.
-- **Over-specified**: Too much implementation detail, too many sub-steps for one story, or solution prescribed instead of outcome. The AI should suggest what to trim or move so the story stays fit for one sprint or one outcome.
-- **Fit for scope and intent**: Clear persona, capability, benefit, and testable AC; appropriate size. The AI should state briefly why it’s ready (and, if you use DoR, that DoR is satisfied).
-
-Include this assessment in the **interactive feedback loop**: present story → assess under-/over-/fit → list ambiguities → ask clarification → re-refine until the PO/stakeholder approves. That way the DevOps team gets to know if a story is under-/over-specified or actually fitting for scope and intent before updating the backlog.
-
-### Step 4: Preview and Apply Refinement
-
-Once validated, the refinement can be previewed or applied:
-
-**Preview Mode (Default - Safe)**:
-
-- Shows what will be updated (title, body) vs preserved (assignees, tags, state, priority, etc.)
-- **Displays assignee information**: Always shows assignee(s) or "Unassigned" status for each item
-- **Displays acceptance criteria**: Always shows acceptance criteria if required by template (even when empty, shows `(empty - required field)` indicator)
-- **Displays required fields**: All required fields from the template are always displayed, even when empty, to help copilot identify missing elements
-- Displays original vs refined content diff
-- **Does NOT write to remote backlog** (safe by default)
-
-**Progress Indicators**:
-
-During initialization (typically 5-10 seconds, longer in corporate environments with security scans/firewalls), the command shows detailed progress:
-
-```bash
-⏱️ Started: 2026-01-27 15:34:05
-⠋ ✓ Templates initialized 0:00:02
-⠋ ✓ Template detector ready 0:00:00
-⠋ ✓ AI refiner ready 0:00:00
-⠋ ✓ Adapter registry ready 0:00:00
-⠋ ✓ Configuration validated 0:00:00
-⠸ ✓ Fetched backlog items 0:00:01
-```
-
-This provides clear feedback during the initialization phase, especially important in corporate environments where network latency and security scans can cause delays.
-
-**Complete Preview Output Example**:
-
-```
-Preview Mode: Full Item Details
-Title: Fix the error
-URL: https://dev.azure.com/dominikusnold/69b5d0c2-2400-470d-b937-b5205503a679/_apis/wit/workItems/185
-State: new
-Provider: ado
-Assignee: Unassigned
-
-Story Metrics:
- - Priority: 2 (1=highest)
- - Work Item Type: User Story
-
-Acceptance Criteria:
-╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
-│ <div><ul><li>quality of this story needs to comply with devops scrum standards. </li> </ul> </div> │
-╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-
-Body:
-╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
-│ <div>This story is here to be refined. </div> │
-╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-
-Target Template: Azure DevOps Work Item (ID: ado_work_item_v1)
-Template Description: Work item template optimized for Azure DevOps with area path and iteration path support
-```
-
-**Note**: If a required field (like Acceptance Criteria) is empty but required by the template, it will show:
-
-```
-Acceptance Criteria:
-╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
-│ (empty - required field) │
-╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-```
-
-This helps copilot identify missing elements that need to be added during refinement.
-
-**Write Mode (Explicit Opt-in)**:
-
-- Requires `--write` flag to explicitly opt-in
-- Updates `BacklogItem.body_markdown` with refined content
-- Sets `refinement_applied = True`
-- 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**:
-
-- **Updated**: `title`, `body_markdown`
-- **Preserved**: `assignees`, `tags`, `state`, `priority`, `due_date`, `story_points`, and all other metadata
-
-```bash
-# Preview mode (default - safe, no writeback)
-specfact backlog ceremony refinement github --preview --search "is:open"
-
-# Write mode (explicit opt-in required)
-specfact backlog ceremony refinement github --write --search "is:open"
-
-# Auto-accept high-confidence refinements (>= 0.85) and write
-specfact backlog ceremony refinement github --auto-accept-high-confidence --write --search "is:open"
-```
-
-### Step 4.5: Definition of Ready (DoR) Validation (Optional)
-
-If `--check-dor` flag is set, SpecFact CLI validates backlog items against Definition of Ready rules:
-
-- Loads DoR configuration from `.specfact/dor.yaml` (repo-level)
-- Validates required fields (story_points, priority, business_value, acceptance_criteria, dependencies)
-- Displays DoR status before refinement
-- Warns if items are not ready for sprint planning
-
-```bash
-# Check DoR before refinement
-specfact backlog ceremony refinement github --check-dor --labels feature
-```
-
-**DoR Configuration** (`.specfact/dor.yaml`):
-
-```yaml
-rules:
- story_points: true
- priority: true
- business_value: true
- acceptance_criteria: true
- dependencies: false # Optional
-```
-
-### Step 5: OpenSpec Integration (Optional)
-
-Refined items can be imported into OpenSpec bundles:
-
-```bash
-# Import to OpenSpec bundle
-specfact backlog ceremony refinement github \
- --bundle my-project \
- --auto-bundle \
- --search "is:open"
-```
-
-This creates OpenSpec change proposals with:
-
-- Refined content in template-compliant format
-- Source tracking metadata (template_id, refinement_confidence, etc.)
-- Link to original backlog item
-
----
-
-## Pre-built Templates
-
-SpecFact CLI includes four pre-built templates:
-
-### User Story Template (`user_story_v1`)
-
-Standard user story format with:
-
-- **As a** (user persona)
-- **I want** (capability)
-- **So that** (benefit)
-- **Acceptance Criteria** (testable conditions)
-
-**Example**:
-
-```markdown
-## As a
-Customer
-
-## I want
-To reset my password via email
-
-## So that
-I can regain access to my account when I forget my password
-
-## Acceptance Criteria
-- User can request password reset from login page
-- System sends reset email with secure token
-- User can set new password using token
-- Token expires after 24 hours
-```
-
-### Defect Template (`defect_v1`)
-
-Bug report format with:
-
-- **Summary** (brief description)
-- **Steps to Reproduce** (reproduction steps)
-- **Expected Behavior** (what should happen)
-- **Actual Behavior** (what actually happens)
-- **Environment** (OS, browser, version, etc.)
-
-**Example**:
-
-```markdown
-## Summary
-Login button does not respond on mobile Safari
-
-## Steps to Reproduce
-1. Open app on iPhone Safari
-2. Enter credentials
-3. Tap "Login" button
-
-## Expected Behavior
-User is redirected to dashboard
-
-## Actual Behavior
-Button does not respond, no action occurs
-
-## Environment
-- OS: iOS 17.0
-- Browser: Safari 17.0
-- Device: iPhone 14 Pro
-```
-
-### Spike Template (`spike_v1`)
-
-Research spike format with:
-
-- **Research Question** (what needs to be investigated)
-- **Research Approach** (how to investigate)
-- **Findings** (what was discovered)
-- **Recommendation** (what to do next)
-
-### Enabler Template (`enabler_v1`)
-
-Enabler work format with:
-
-- **Enabler Description** (what capability is being enabled)
-- **Dependencies** (what this enables)
-- **Implementation Approach** (how to implement)
-- **Success Criteria** (how to measure success)
-
----
-
-## Command Reference
-
-### `specfact backlog ceremony refinement`
-
-Refine backlog items using AI-assisted template matching.
-
-```bash
-specfact backlog ceremony refinement <ADAPTER> [OPTIONS]
-```
-
-**Arguments**:
-
-- `ADAPTER` - Backlog adapter name (`github`, `ado`, etc.)
-
-**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
-- `--auto-accept-high-confidence` - Auto-accept refinements with confidence >= 0.85
-- `--bundle`, `-b` - OpenSpec bundle path to import refined items
-- `--auto-bundle` - Auto-import refined items to OpenSpec bundle
-
-**Examples**:
-
-```bash
-# Refine GitHub issues (auto-detect template)
-specfact backlog ceremony refinement github --search "is:open label:feature"
-
-# Filter by labels and state
-specfact backlog ceremony refinement github --labels feature,enhancement --state open
-
-# Filter by sprint and assignee
-specfact backlog ceremony refinement github --sprint "Sprint 1" --assignee dev1
-
-# Filter by framework and persona (Scrum + Product Owner)
-specfact backlog ceremony refinement github --framework scrum --persona product-owner --labels feature
-
-# Refine with specific template
-specfact backlog ceremony refinement github --template user_story_v1 --search "is:open"
-
-# Check Definition of Ready before refinement
-specfact backlog ceremony refinement github --check-dor --labels feature
-
-# Preview refinement without writing (default - safe mode)
-specfact backlog ceremony refinement github --preview --labels feature
-
-# Write refinement to backlog (explicit opt-in required)
-specfact backlog ceremony refinement github --write --labels feature
-
-# Auto-accept high-confidence refinements
-specfact backlog ceremony refinement github --auto-accept-high-confidence --search "is:open"
-
-# Refine and import to OpenSpec bundle
-specfact backlog ceremony refinement github \
- --bundle my-project \
- --auto-bundle \
- --search "is:open label:enhancement"
-
-# Refine ADO work items with sprint filter
-specfact backlog ceremony refinement ado --sprint "Sprint 1" --state Active
-
-# Refine ADO work items with custom field mapping
-specfact backlog ceremony refinement ado \
- --ado-org my-org \
- --ado-project my-project \
- --custom-field-mapping .specfact/templates/backlog/field_mappings/ado_custom.yaml \
- --state Active
-
-# Refine ADO work items with iteration path
-specfact backlog ceremony refinement ado --iteration "Project\\Release 1\\Sprint 1"
-```
-
-### 4. Export Full Comment Context for Copilot
-
-`specfact backlog ceremony refinement --export-to-tmp` now includes issue/work item comments (when adapter supports comments, including ADO) so refinement context is complete by default.
-
-```bash
-# Export with full comment history (default, no truncation)
-specfact backlog ceremony refinement ado \
- --ado-org my-org \
- --ado-project my-project \
- --state Active \
- --export-to-tmp
-
-# Optional: preview only first N comments in terminal output
-specfact backlog ceremony refinement ado \
- --ado-org my-org \
- --ado-project my-project \
- --state Active \
- --preview \
- --first-comments 3
-
-# Optional: preview only last N comments in terminal output
-specfact backlog ceremony refinement ado \
- --ado-org my-org \
- --ado-project my-project \
- --state Active \
- --preview \
- --last-comments 4
-```
-
-Preview defaults to the last 2 comments per item to keep CLI output readable.
-`--first-comments N` and `--last-comments N` are mutually exclusive and affect preview density and write-mode prompt comment context.
-In `--write` workflows, prompts include full comment history by default unless a first/last comment window is provided.
-`--export-to-tmp` always writes full comment history.
-The export file now includes a `## Copilot Instructions` block and per-item template guidance, and Copilot should follow those embedded instructions when refining.
-For export-driven refinement, treat the embedded file instructions as the canonical format contract.
-For `--import-from-tmp`, ensure the refined artifact excludes the instruction header and retains only `## Item N:` sections with refined fields.
-
-Use `--first-issues N` or `--last-issues N` to process only a first/last slice of filtered issues in a refine run (mutually exclusive).
-Issue windowing is based on numeric issue/work-item IDs: lower IDs are treated as older (`--first-issues`), higher IDs as newer (`--last-issues`).
-
-### 5. Shared Backlog Filter Parity (Refine + Daily)
-
-`specfact backlog ceremony refinement` and `specfact backlog ceremony standup` now share the same global backlog scoping semantics for common workflows:
-
-- `--search`, `--release`, `--id` for consistent item selection
-- `--first-issues N` / `--last-issues N` for deterministic oldest/newest issue windows (numeric ID ordering)
-- comment-window options where applicable:
- - **Refine**: `--first-comments N` / `--last-comments N` affect preview and write-prompt context
- - **Daily export/summarize**: `--first-comments N` / `--last-comments N` scope `--comments` output
- - **Daily interactive**: latest comment by default; explicit comment-window flags override that default
-
-For day-to-day team flow, this means you can switch between `backlog ceremony standup` and
-`backlog ceremony refinement` without changing filter mental models.
-
----
-
-## Workflow Integration
-
-### Command Chaining: Refine → Sync
-
-The most common workflow is to refine backlog items and then sync them to external tools. This command chaining workflow is fully supported and tested:
-
-**Workflow**: `backlog ceremony refinement` → `sync bridge`
-
-1. **Refine Backlog Items**: Use `specfact backlog ceremony refinement` to standardize backlog items with templates
-2. **Sync to External Tools**: Use `specfact project sync bridge` to sync refined items back to backlog tools (GitHub, ADO, etc.)
-
-```bash
-# Complete command chaining workflow
-# 1. Refine GitHub issues (with writeback)
-specfact backlog ceremony refinement github \
- --repo-owner my-org --repo-name my-repo \
- --write \
- --labels feature \
- --state open
-
-# 2. Sync refined items to external tool (same or different adapter)
-specfact project sync bridge --adapter github \
- --repo-owner my-org --repo-name my-repo \
- --backlog-ids 123,456 \
- --mode export-only
-
-# Cross-adapter sync: Refine from GitHub → Sync to ADO
-specfact backlog ceremony refinement github \
- --repo-owner my-org --repo-name my-repo \
- --write \
- --labels feature
-
-specfact project sync bridge --adapter ado \
- --ado-org my-org --ado-project my-project \
- --backlog-ids 123,456 \
- --mode export-only
-```
-
-**Key Benefits**:
-
-- **Lossless Preservation**: Original backlog data is preserved during refinement
-- **Cross-Adapter Support**: Refine from one provider (GitHub) and sync to another (ADO)
-- **OpenSpec Integration**: Refined items can include OpenSpec comments without replacing the body
-- **Field Preservation**: Only `title` and `body_markdown` are updated; all other fields (assignees, tags, state, priority, etc.) are preserved
-- **Generic State Mapping**: Automatic state preservation during cross-adapter sync using OpenSpec as intermediate format
-
-### Cross-Adapter State Mapping
-
-When syncing backlog items between different adapters (e.g., GitHub ↔ ADO), SpecFact CLI uses a **generic state mapping mechanism** that preserves the original state across adapters.
-
-**How It Works**:
-
-1. **State Preservation During Import**: When backlog items are imported into a bundle, the original `source_state` (e.g., "open", "closed", "New", "Active") is stored in `source_metadata["source_state"]` within the bundle entry.
-
-2. **Generic State Mapping**: During cross-adapter export, the system uses OpenSpec as an intermediate format:
- - **Step 1**: Source adapter state → OpenSpec status (using source adapter's mapping)
- - **Step 2**: OpenSpec status → Target adapter state (using target adapter's mapping)
-
-3. **Bidirectional Support**: The mapping works in both directions:
- - **GitHub → ADO**: GitHub "open" → OpenSpec "proposed" → ADO "New"
- - **GitHub → ADO**: GitHub "closed" → OpenSpec "applied" → ADO "Closed"
- - **ADO → GitHub**: ADO "New" → OpenSpec "proposed" → GitHub "open"
- - **ADO → GitHub**: ADO "Closed" → OpenSpec "applied" → GitHub "closed"
-
-**Example: Cross-Adapter Sync with State Preservation**:
-
-```bash
-# 1. Import closed GitHub issues into bundle (state "closed" is preserved)
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner nold-ai --repo-name specfact-cli \
- --backlog-ids 110,122
-
-# 2. Export to ADO (state is automatically mapped: closed → Closed)
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org dominikusnold --ado-project "SpecFact CLI" \
- --bundle cross-sync-test --change-ids add-ado-backlog-adapter,add-template-driven-backlog-refinement
-
-# Result: ADO work items are created with "Closed" state (matching GitHub "closed")
-```
-
-**State Mapping Guarantees**:
-
-- **Open Issues**: GitHub "open" ↔ ADO "New" (both represent active work)
-- **Closed Issues**: GitHub "closed" ↔ ADO "Closed" (both represent completed work)
-- **Active Work**: ADO "Active" → GitHub "open" (active work remains open)
-- **Resolved Work**: ADO "Resolved" → GitHub "closed" (resolved work is closed)
-
-**Implementation Details**:
-
-- The generic mapping is implemented in `BacklogAdapterMixin.map_backlog_state_between_adapters()`
-- Each adapter provides bidirectional mappings:
- - `map_backlog_status_to_openspec()`: Adapter state → OpenSpec status
- - `map_openspec_status_to_backlog()`: OpenSpec status → Adapter state
-- The mapping is automatic when `source_state` and `source_type` are present in bundle entries
-- No manual state mapping is required - the system handles it automatically
-
-### With DevOps Adapter Integration
-
-Backlog refinement works seamlessly with the [DevOps Adapter Integration](../guides/devops-adapter-integration.md):
-
-1. **Import Backlog Items**: Use `specfact project sync bridge` to import backlog items as OpenSpec proposals
-2. **Refine Items**: Use `specfact backlog ceremony refinement` to standardize imported items
-3. **Export Refined Items**: Use `specfact project sync bridge` to export refined proposals back to backlog tools
-
-```bash
-# Complete workflow
-# 1. Import GitHub issues as OpenSpec proposals
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner my-org --repo-name my-repo \
- --backlog-ids 123,456
-
-# 2. Refine imported items
-specfact backlog ceremony refinement github --bundle my-project --auto-bundle \
- --search "is:open"
-
-# 3. Export refined proposals back to GitHub
-specfact project sync bridge --adapter github --mode export-only \
- --bundle my-project --change-ids <refined-change-id>
-```
-
-### With IDE AI Copilots
-
-The refinement workflow is designed for IDE AI copilots:
-
-1. **Generate Prompt**: SpecFact CLI generates a refinement prompt
-2. **Copy to IDE**: Copy the prompt to your IDE AI copilot (Cursor, Claude Code, etc.)
-3. **Execute Refinement**: IDE AI copilot executes the refinement using its native LLM
-4. **Paste Result**: Paste the refined content back into SpecFact CLI
-5. **Validate**: SpecFact CLI validates and scores the refinement
-
-**Example with Cursor**:
-
-```bash
-# 1. Run refinement command
-specfact backlog ceremony refinement github --search "is:open label:feature"
-
-# 2. CLI displays prompt:
-# "Refine the following backlog item into a user story template..."
-# [Copy prompt]
-
-# 3. In Cursor IDE:
-# /refine [paste prompt]
-
-# 4. Cursor returns refined content:
-# "## As a\nCustomer\n\n## I want\n..."
-
-# 5. Paste refined content back into CLI
-# CLI validates and applies refinement
-```
-
----
-
-## Field Mapping and Customization
-
-### Custom Field Mappings for Azure DevOps
-
-If your Azure DevOps organization uses custom process templates with non-standard field names, you can create custom field mappings to map your ADO fields to canonical field names.
-
-**Quick Example**:
-
-```bash
-# Use custom field mapping file
-specfact backlog ceremony refinement ado \
- --ado-org my-org \
- --ado-project my-project \
- --custom-field-mapping .specfact/templates/backlog/field_mappings/ado_custom.yaml \
- --state Active
-```
-
-**Custom Mapping File Format**:
-
-Create a YAML file at `.specfact/templates/backlog/field_mappings/ado_custom.yaml`:
-
-```yaml
-framework: scrum
-
-field_mappings:
- System.Description: description
- Custom.StoryPoints: story_points
- Custom.BusinessValue: business_value
- Custom.Priority: priority
-
-work_item_type_mappings:
- Product Backlog Item: User Story
- Requirement: User Story
-```
-
-**See Also**: [Custom Field Mapping Guide](./custom-field-mapping.md) for complete documentation on field mapping templates, framework-specific examples, and best practices.
-
-## Template Customization
-
-### Creating Custom Templates
-
-Templates are YAML files with the following structure:
-
-```yaml
-template_id: custom_template_v1
-name: Custom Template
-scope: corporate # or "team"
-description: Custom template for specific use case
-
-# Persona, framework, and provider filtering (optional)
-personas: ["product-owner", "developer"] # Empty = all personas
-framework: "scrum" # None = framework-agnostic
-provider: "github" # None = provider-agnostic
-
-required_sections:
- - "## Section 1"
- - "## Section 2"
-
-optional_sections:
- - "## Notes"
- - "## References"
-
-body_patterns:
- section_pattern: "section.*pattern"
-
-title_patterns:
- - "^Feature:"
-```
-
-Save custom templates to your project directory:
-
-- **Default templates**: `.specfact/templates/backlog/defaults/`
-- **Framework-specific**: `.specfact/templates/backlog/frameworks/<framework>/` (e.g., `scrum/`, `safe/`)
-- **Persona-specific**: `.specfact/templates/backlog/personas/<persona>/` (e.g., `product-owner/`, `developer/`)
-- **Provider-specific**: `.specfact/templates/backlog/providers/<provider>/` (e.g., `github/`, `ado/`)
-
-**Built-in templates** (included with SpecFact CLI):
-
-- Location: `resources/templates/backlog/` (in the SpecFact CLI package)
-- Same subdirectory structure: `defaults/`, `frameworks/`, `personas/`, `providers/`
-
-### Loading Custom Templates
-
-Templates are automatically loaded in priority order (custom templates override built-in):
-
-1. **Project templates** (`.specfact/templates/backlog/`) - Highest priority, overrides built-in
-2. **Built-in templates** (`resources/templates/backlog/`) - Included with package
-3. **Legacy location** (`src/specfact_cli/templates/`) - Fallback for backward compatibility
-
-Within each location, templates are loaded from:
-
-- `defaults/` subdirectory
-- `frameworks/<framework>/` subdirectories
-- `personas/<persona>/` subdirectories
-- `providers/<provider>/` subdirectories
-
-**Template Resolution**:
-
-When using `--persona`, `--framework`, or provider-specific filtering, SpecFact CLI automatically resolves templates using priority-based matching:
-
-```bash
-# Automatically resolves to most specific template match
-specfact backlog ceremony refinement github --framework scrum --persona product-owner --labels feature
-
-# Force specific template (overrides priority-based resolution)
-specfact backlog ceremony refinement github --template custom_template_v1
-```
-
----
-
-## Best Practices
-
-### 1. Start with Auto-Detection
-
-Let SpecFact CLI detect templates automatically before forcing specific templates:
-
-```bash
-# Good: Auto-detect first
-specfact backlog ceremony refinement github --search "is:open"
-
-# Then use specific template if needed
-specfact backlog ceremony refinement github --template user_story_v1 --search "is:open"
-```
-
-### 2. Review Low-Confidence Refinements
-
-Refinements with confidence < 0.85 may need manual review:
-
-```bash
-# Review low-confidence refinements manually
-specfact backlog ceremony refinement github --search "is:open"
-# CLI will prompt for confirmation on low-confidence refinements
-```
-
-### 3. Use Auto-Accept for High-Confidence
-
-For high-confidence refinements (>= 0.85), use auto-accept:
-
-```bash
-# Auto-accept high-confidence refinements
-specfact backlog ceremony refinement github --auto-accept-high-confidence --search "is:open"
-```
-
-### 4. Integrate with OpenSpec Bundles
-
-Import refined items to OpenSpec bundles for full workflow integration:
-
-```bash
-# Refine and import to bundle
-specfact backlog ceremony refinement github \
- --bundle my-project \
- --auto-bundle \
- --search "is:open"
-```
-
-### 5. Preserve Original Data
-
-SpecFact CLI preserves original backlog data in `provider_fields` for lossless round-trip:
-
-- Original title and body
-- Provider-specific metadata
-- Labels, assignees, milestones
-- Custom fields
-- Sprint and release information (extracted from milestones/iteration paths)
-
-### 6. Use Filtering for Agile Workflows
-
-Leverage filtering options for common agile/scrum workflows:
-
-```bash
-# Refine items in current sprint
-specfact backlog ceremony refinement github --sprint "Sprint 1" --state open
-
-# Refine items assigned to specific developer
-specfact backlog ceremony refinement github --assignee dev1 --labels bug
-
-# Refine items for specific release
-specfact backlog ceremony refinement ado --release "Release 1.0" --state Active
-
-# Use persona/framework filtering for role-specific templates
-specfact backlog ceremony refinement github --persona product-owner --framework scrum --labels feature
-```
-
-### 7. Check Definition of Ready (DoR)
-
-Use DoR validation to ensure items are ready for sprint planning:
-
-```bash
-# Check DoR before refinement
-specfact backlog ceremony refinement github --check-dor --labels feature
-
-# DoR configuration in .specfact/dor.yaml
-rules:
- story_points: true
- priority: true
- business_value: true
- acceptance_criteria: true
-```
-
----
-
-## Troubleshooting
-
-### Template Not Detected
-
-If template detection fails:
-
-1. **Check Template Structure**: Ensure backlog item has required section headings
-2. **Check Patterns**: Verify title/body matches template patterns
-3. **Force Template**: Use `--template` to force specific template
-
-```bash
-# Force template if auto-detection fails
-specfact backlog ceremony refinement github --template user_story_v1 --search "is:open"
-```
-
-### Low Confidence Scores
-
-Low confidence scores (< 0.6) indicate:
-
-- Missing required sections
-- TODO markers in refined content
-- NOTES sections indicating uncertainty
-- Insufficient content
-
-**Solutions**:
-
-- Review original backlog item for completeness
-- Manually edit refined content before applying
-- Use `--template` to force template structure
-
-### Adapter Search Not Available
-
-If adapter search methods are not available:
-
-```bash
-# CLI will show warning:
-# "Note: GitHub issue fetching requires adapter.search_issues() implementation"
-```
-
-**Workaround**: Use `specfact project sync bridge` to import backlog items first, then refine:
-
-```bash
-# 1. Import backlog items
-specfact project sync bridge --adapter github --mode bidirectional \
- --backlog-ids 123,456
-
-# 2. Refine imported items from bundle
-specfact backlog ceremony refinement github --bundle my-project --auto-bundle
-```
-
-### Azure DevOps Adapter Configuration
-
-The Azure DevOps (ADO) adapter supports both **Azure DevOps Services (cloud)** and **Azure DevOps Server (on-premise)**. Configuration differs based on your environment.
-
-#### Azure DevOps Services (Cloud)
-
-For cloud-based Azure DevOps, use the standard format:
-
-```bash
-# Basic configuration
-specfact backlog ceremony refinement ado \
- --ado-org "my-org" \
- --ado-project "my-project" \
- --state Active
-
-# With custom base URL (defaults to https://dev.azure.com)
-specfact backlog ceremony refinement ado \
- --ado-org "my-org" \
- --ado-project "my-project" \
- --ado-base-url "https://dev.azure.com" \
- --state Active
-```
-
-**URL Format**: `https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=7.1`
-
-#### Azure DevOps Server (On-Premise)
-
-For on-premise Azure DevOps Server, the URL format depends on whether the collection is included in the base URL:
-
-**Option 1: Collection in Base URL**
-
-If your base URL already includes the collection:
-
-```bash
-# Collection already in base_url
-specfact backlog ceremony refinement ado \
- --ado-base-url "https://devops.company.com/tfs/DefaultCollection" \
- --ado-project "my-project" \
- --state Active
-```
-
-**URL Format**: `https://server/tfs/collection/{project}/_apis/wit/wiql?api-version=7.1`
-
-**Option 2: Collection Provided Separately**
-
-If your base URL doesn't include the collection:
-
-```bash
-# Collection provided as org parameter
-specfact backlog ceremony refinement ado \
- --ado-base-url "https://devops.company.com" \
- --ado-org "DefaultCollection" \
- --ado-project "my-project" \
- --state Active
-```
-
-**URL Format**: `https://server/{collection}/{project}/_apis/wit/wiql?api-version=7.1`
-
-#### ADO API Endpoint Requirements
-
-**WIQL Query Endpoint** (POST):
-
-- **URL**: `{base_url}/{org}/{project}/_apis/wit/wiql?api-version=7.1`
-- **Method**: POST
-- **Body**: `{"query": "SELECT [System.Id] FROM WorkItems WHERE ..."}`
-- **Headers**: `Content-Type: application/json`, `Accept: application/json`
-- **Note**: The `api-version` parameter is **required** for all ADO API calls
-
-**Work Items Batch GET Endpoint**:
-
-- **URL**: `{base_url}/{org}/_apis/wit/workitems?ids={ids}&api-version=7.1`
-- **Method**: GET
-- **Note**: This endpoint is at the **organization level** (not project level) for fetching work item details by IDs
-
-#### Common ADO API Errors
-
-**Error: "No HTTP resource was found that matches the request URI"**
-
-- **Cause**: Missing `api-version` parameter or incorrect URL format
-- **Solution**: Ensure `api-version=7.1` is included in all ADO API URLs
-
-**Error: "The requested resource does not support http method 'GET'"**
-
-- **Cause**: Attempting to use GET on WIQL endpoint (which requires POST)
-- **Solution**: WIQL queries must use POST method with JSON body
-
-**Error: Organization removed from request string**
-
-- **Cause**: Incorrect base URL format (may already include organization/collection)
-- **Solution**: Check if base URL already includes collection, adjust `--ado-org` parameter accordingly
-
-#### Authentication
-
-ADO adapter supports multiple authentication methods:
-
-```bash
-# Method 1: Environment variable
-export AZURE_DEVOPS_TOKEN="your-pat-token"
-specfact backlog ceremony refinement ado --ado-org "my-org" --ado-project "my-project"
-
-# Method 2: CLI parameter
-specfact backlog ceremony refinement ado \
- --ado-org "my-org" \
- --ado-project "my-project" \
- --ado-token "your-pat-token"
-
-# Method 3: Stored token (via device code flow)
-specfact backlog auth azure-devops # Interactive device code flow
-specfact backlog ceremony refinement ado --ado-org "my-org" --ado-project "my-project"
-```
-
----
-
-## Related Documentation
-
-- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - Complete guide for GitHub Issues and Azure DevOps integration
-- **[Command Reference](../reference/commands.md)** - Complete command documentation
-- **[Agile/Scrum Workflows](../guides/agile-scrum-workflows.md)** - Persona-based collaboration for teams
-- **[IDE Integration](../guides/ide-integration.md)** - Set up slash commands in your IDE
-
----
-
-**Happy refining!** 🚀
+The full guide is published on the **canonical modules docs site**: [Backlog refinement](https://modules.specfact.io/bundles/backlog/refinement/)
diff --git a/docs/guides/brownfield-engineer.md b/docs/guides/brownfield-engineer.md
index 254bae99..20c94a76 100644
--- a/docs/guides/brownfield-engineer.md
+++ b/docs/guides/brownfield-engineer.md
@@ -2,373 +2,15 @@
layout: default
title: Modernizing Legacy Code (Brownfield Engineer Guide)
permalink: /guides/brownfield-engineer/
+description: Handoff to the full brownfield engineer guide on the modules documentation site.
redirect_from:
- /brownfield-engineer/
---
-# Guide for Legacy Modernization Engineers
+# Modernizing legacy code (brownfield engineer)
-> **Complete walkthrough for modernizing legacy Python code with SpecFact CLI**
+This guide helps engineers modernize legacy Python systems using SpecFact: extracting specs from code, enforcing contracts, and integrating with your IDE and CI. The detailed walkthrough, examples, and step-by-step commands live on the modules repository documentation.
----
-
-## Your Challenge
-
-You're responsible for modernizing a legacy Python system that:
-
-- Has minimal or no documentation
-- Was built by developers who have left
-- Contains critical business logic you can't risk breaking
-- Needs migration to modern Python, cloud infrastructure, or microservices
-
-**Sound familiar?** You're not alone. 70% of IT budgets are consumed by legacy maintenance, and the legacy modernization market is $25B+ and growing.
-
----
-
-## SpecFact for Brownfield: Your Safety Net
-
-SpecFact CLI is designed specifically for your situation. It provides:
-
-1. **Automated spec extraction** (code2spec) - Understand what your code does in < 10 seconds
-2. **Runtime contract enforcement** - Prevent regressions during modernization
-3. **Symbolic execution** - Discover hidden edge cases with CrossHair
-4. **Formal guarantees** - Mathematical verification, not probabilistic LLM suggestions
-5. **CLI-first integration** - Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. Works offline, no account required, no vendor lock-in.
-
----
-
-## Step 1: Understand What You Have
-
-**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.
-
-### Extract Specs from Legacy Code
-
-```bash
-# Analyze your legacy codebase
-specfact code import legacy-api --repo ./legacy-app
-
-# For large codebases or multi-project repos, analyze specific modules:
-specfact code import core-module --repo ./legacy-app --entry-point src/core
-specfact code import api-module --repo ./legacy-app --entry-point src/api
-```
-
-**What you get:**
-
-- ✅ Auto-generated feature map of existing functionality
-- ✅ Extracted user stories from code patterns
-- ✅ Dependency graph showing module relationships
-- ✅ Business logic documentation from function signatures
-- ✅ Edge cases discovered via symbolic execution
-
-**Example output:**
-
-```text
-✅ Analyzed 47 Python files
-✅ Extracted 23 features:
-
- - FEATURE-001: User Authentication (95% confidence)
- - FEATURE-002: Payment Processing (92% confidence)
- - FEATURE-003: Order Management (88% confidence)
- ...
-✅ Generated 112 user stories from existing code patterns
-✅ Detected 6 edge cases with CrossHair symbolic execution
-⏱️ Completed in 8.2 seconds
-```
-
-**Time saved:** 60-120 hours of manual documentation work → **8 seconds**
-
-**💡 Partial Repository Coverage:**
-
-For large codebases or monorepos with multiple projects, you can analyze specific subdirectories using `--entry-point`:
-
-```bash
-# Analyze only the core module
-specfact code import core-module --repo . --entry-point src/core
-
-# Analyze only the API service
-specfact code import api-service --repo . --entry-point projects/api-service
-```
-
-This enables:
-
-- **Faster analysis** - Focus on specific modules for quicker feedback
-- **Incremental modernization** - Modernize one module at a time
-- **Multi-plan support** - Create separate plan bundles for different projects/modules
-- **Better organization** - Keep plans organized by project boundaries
-
-**💡 Tip**: After importing, the CLI may suggest enforcing SDD compliance for Spec-Kit integration. Run SDD enforcement to validate compliance:
-
-```bash
-# Enforce SDD compliance for your bundle
-specfact govern enforce sdd <bundle-name>
-```
-
-This is especially useful if you plan to sync with Spec-Kit later.
-
----
-
-## Step 2: Add Contracts to Critical Paths
-
-### Identify Critical Functions
-
-SpecFact helps you identify which functions are critical (high risk, high business value):
-
-```bash
-# Review extracted plan to identify critical paths
-cat .specfact/projects/<bundle-name>/bundle.manifest.yaml
-```
-
-### Add Runtime Contracts
-
-Add contract decorators to critical functions:
-
-```python
-# Before: Undocumented legacy function
-def process_payment(user_id, amount, currency):
- # 80 lines of legacy code with hidden business rules
- ...
-
-# After: Contract-enforced function
-import icontract
-
-@icontract.require(lambda amount: amount > 0, "Payment amount must be positive")
-@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
-@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
-def process_payment(user_id, amount, currency):
- # Same 80 lines of legacy code
- # Now with runtime enforcement
- ...
-```
-
-**What this gives you:**
-
-- ✅ Runtime validation catches invalid inputs immediately
-- ✅ Prevents regressions during refactoring
-- ✅ Documents expected behavior (executable documentation)
-- ✅ CrossHair discovers edge cases automatically
-
----
-
-## Step 3: Modernize with Confidence
-
-### Refactor Safely
-
-With contracts in place, you can refactor knowing that violations will be caught:
-
-```python
-# Refactored version (same contracts)
-@icontract.require(lambda amount: amount > 0, "Payment amount must be positive")
-@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
-@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
-def process_payment(user_id, amount, currency):
- # Modernized implementation
- # If contract violated → exception raised immediately
- ...
-
-```
-
-### Catch Regressions Automatically
-
-```python
-# During modernization, accidentally break contract:
-process_payment(user_id=-1, amount=-50, currency="XYZ")
-
-# Runtime enforcement catches it:
-# ❌ ContractViolation: Payment amount must be positive (got -50)
-# at process_payment() call from refactored checkout.py:142
-# → Prevented production bug during modernization!
-```
-
----
-
-## Step 4: Discover Hidden Edge Cases
-
-### CrossHair Symbolic Execution
-
-SpecFact uses CrossHair to discover edge cases that manual testing misses:
-
-```python
-# Legacy function with hidden edge case
-@icontract.require(lambda numbers: len(numbers) > 0)
-@icontract.ensure(lambda numbers, result: len(numbers) == 0 or min(numbers) > result)
-def remove_smallest(numbers: List[int]) -> int:
- """Remove and return smallest number from list"""
- smallest = min(numbers)
- numbers.remove(smallest)
- return smallest
-
-# CrossHair finds counterexample:
-# Input: [3, 3, 5] → After removal: [3, 5], min=3, returned=3
-# ❌ Postcondition violated: min(numbers) > result fails when duplicates exist!
-# CrossHair generates concrete failing input: [3, 3, 5]
-```
-
-**Why this matters:**
-
-- ✅ Discovers edge cases LLMs miss
-- ✅ Mathematical proof of violations (not probabilistic)
-- ✅ Generates concrete test inputs automatically
-- ✅ Prevents production bugs before they happen
-
----
-
-## Real-World Example: Django Legacy App
-
-### The Problem
-
-You inherited a 3-year-old Django app with:
-
-- No documentation
-- No type hints
-- No tests
-- 15 undocumented API endpoints
-- Business logic buried in views
-
-### The Solution
-
-```bash
-# Step 1: Extract specs
-specfact code import customer-portal --repo ./legacy-django-app
-
-# Output:
-✅ Analyzed 47 Python files
-✅ Extracted 23 features (API endpoints, background jobs, integrations)
-✅ Generated 112 user stories from existing code patterns
-✅ Time: 8 seconds
-```
-
-### The Results
-
-- ✅ Legacy app fully documented in < 10 minutes
-- ✅ Prevented 4 production bugs during refactoring
-- ✅ New developers onboard 60% faster
-- ✅ CrossHair discovered 6 hidden edge cases
-
----
-
-## ROI: Time and Cost Savings
-
-### Manual Approach
-
-| Task | Time Investment | Cost (@$150/hr) |
-|------|----------------|-----------------|
-| Manually document 50-file legacy app | 80-120 hours | $12,000-$18,000 |
-| Write tests for undocumented code | 100-150 hours | $15,000-$22,500 |
-| Debug regression during refactor | 40-80 hours | $6,000-$12,000 |
-| **TOTAL** | **220-350 hours** | **$33,000-$52,500** |
-
-### SpecFact Automated Approach
-
-| Task | Time Investment | Cost (@$150/hr) |
-|------|----------------|-----------------|
-| Run code2spec extraction | 10 minutes | $25 |
-| Review and refine extracted specs | 8-16 hours | $1,200-$2,400 |
-| Add contracts to critical paths | 16-24 hours | $2,400-$3,600 |
-| CrossHair edge case discovery | 2-4 hours | $300-$600 |
-| **TOTAL** | **26-44 hours** | **$3,925-$6,625** |
-
-### ROI: **87% time saved, $26,000-$45,000 cost avoided**
-
----
-
-## Integration with Your Workflow
-
-SpecFact CLI integrates seamlessly with your existing tools:
-
-- **VS Code**: Use pre-commit hooks to catch breaking changes before commit
-- **Cursor**: AI assistant workflows catch regressions during refactoring
-- **GitHub Actions**: CI/CD integration blocks bad code from merging
-- **Pre-commit hooks**: Local validation prevents breaking changes
-- **Any IDE**: Pure CLI-first approach—works with any editor
-
-**See real examples**: [Integration Showcases](../examples/integration-showcases/) - 5 complete examples showing bugs fixed via integrations
-
-## Best Practices
-
-### 1. Start with Shadow Mode
-
-Begin in shadow mode to observe without blocking:
-
-```bash
-specfact code import legacy-api --repo . --shadow-only
-```
-
-### 2. Add Contracts Incrementally
-
-Don't try to contract everything at once:
-
-1. **Week 1**: Add contracts to 3-5 critical functions
-2. **Week 2**: Expand to 10-15 functions
-3. **Week 3**: Add contracts to all public APIs
-4. **Week 4+**: Add contracts to internal functions as needed
-
-### 3. Use CrossHair for Edge Case Discovery
-
-Run CrossHair on critical functions before refactoring:
-
-```bash
-hatch run contract-explore src/payment.py
-```
-
-### 4. Document Your Findings
-
-Keep notes on:
-
-- Edge cases discovered
-- Contract violations caught
-- Time saved on documentation
-- Bugs prevented during modernization
-
----
-
-## Common Questions
-
-### Can SpecFact analyze code with no docstrings?
-
-**Yes.** code2spec analyzes:
-
-- Function signatures and type hints
-- Code patterns and control flow
-- Existing validation logic
-- Module dependencies
-
-No docstrings needed.
-
-### What if the legacy code has no type hints?
-
-**SpecFact infers types** from usage patterns and generates specs. You can add type hints incrementally as part of modernization.
-
-### Can SpecFact handle obfuscated or minified code?
-
-**Limited.** SpecFact works best with:
-
-- Source code (not compiled bytecode)
-- Readable variable names
-
-For heavily obfuscated code, consider deobfuscation first.
-
-### Will contracts slow down my code?
-
-**Minimal impact.** Contract checks are fast (microseconds per call). For high-performance code, you can disable contracts in production while keeping them in tests.
-
----
-
-## Next Steps
-
-1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
-2. **[ROI Calculator](brownfield-roi.md)** - Calculate your time and cost savings
-3. **[Brownfield Journey](brownfield-journey.md)** - Complete modernization workflow
-4. **[Examples](../examples/)** - Real-world brownfield examples
-5. **[FAQ](brownfield-faq.md)** - More brownfield-specific questions
-
----
-
-## Support
-
-- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
-- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
-- 📧 [hello@noldai.com](mailto:hello@noldai.com)
-
----
+**Prerequisites:** [SpecFact CLI installed](https://docs.specfact.io/getting-started/quickstart/); a local clone of the codebase you plan to modernize.
-**Happy modernizing!** 🚀
+**Full guide on the canonical modules docs site:** [Brownfield engineer guide](https://modules.specfact.io/brownfield-engineer/)
diff --git a/docs/guides/brownfield-faq.md b/docs/guides/brownfield-faq.md
index 8120afb0..4e62ae63 100644
--- a/docs/guides/brownfield-faq.md
+++ b/docs/guides/brownfield-faq.md
@@ -1,375 +1,14 @@
---
layout: default
-title: Brownfield Faq
+title: Brownfield FAQ
permalink: /guides/brownfield-faq/
+description: Handoff to brownfield frequently asked questions on the modules documentation site.
---
-# Brownfield Modernization FAQ
+# Brownfield FAQ
-> **Frequently asked questions about using SpecFact CLI for legacy code modernization**
+Answers to common questions about brownfield modernization with SpecFact—scope, performance, tooling, and workflow expectations. The full FAQ is updated with releases on the modules documentation site.
----
-
-## General Questions
-
-### What is brownfield modernization?
-
-**Brownfield modernization** refers to improving, refactoring, or migrating existing (legacy) codebases, as opposed to greenfield development (starting from scratch).
-
-SpecFact CLI is designed specifically for brownfield projects where you need to:
-
-- Understand undocumented legacy code
-- Modernize without breaking existing behavior
-- Extract specs from existing code (code2spec)
-- Enforce contracts during refactoring
-
----
-
-## Code Analysis
-
-### Can SpecFact analyze code with no docstrings?
-
-**Yes.** SpecFact's code2spec analyzes:
-
-- Function signatures and type hints
-- Code patterns and control flow
-- Existing validation logic
-- Module dependencies
-- Commit history and code structure
-
-No docstrings needed. SpecFact infers behavior from code patterns.
-
-### What if the legacy code has no type hints?
-
-**SpecFact infers types** from usage patterns and generates specs. You can add type hints incrementally as part of modernization.
-
-**Example:**
-
-```python
-# Legacy code (no type hints)
-def process_order(user_id, amount):
- # SpecFact infers: user_id: int, amount: float
- ...
-
-# SpecFact generates:
-# - Precondition: user_id > 0, amount > 0
-# - Postcondition: returns Order object
-```
-
-### Can SpecFact handle obfuscated or minified code?
-
-**Limited.** SpecFact works best with:
-
-- Source code (not compiled bytecode)
-- Readable variable names
-- Standard Python patterns
-
-For heavily obfuscated code, consider:
-
-1. Deobfuscation first (if possible)
-2. Manual documentation of critical paths
-3. Adding contracts incrementally to deobfuscated sections
-
-### What about code with no tests?
-
-**SpecFact doesn't require tests.** In fact, code2spec is designed for codebases with:
-
-- No tests
-- No documentation
-- No type hints
-
-SpecFact extracts specs from code structure and patterns, not from tests.
-
----
-
-## Contract Enforcement
-
-### Will contracts slow down my code?
-
-**Minimal impact.** Contract checks are fast (microseconds per call). For high-performance code:
-
-- **Development/Testing:** Keep contracts enabled (catch violations)
-- **Production:** Optionally disable contracts (performance-critical paths only)
-
-**Best practice:** Keep contracts in tests, disable only in production hot paths if needed.
-
-### Can I add contracts incrementally?
-
-**Yes.** Recommended approach:
-
-1. **Week 1:** Add contracts to 3-5 critical functions
-2. **Week 2:** Expand to 10-15 functions
-3. **Week 3:** Add contracts to all public APIs
-4. **Week 4+:** Add contracts to internal functions as needed
-
-Start with shadow mode (observe only), then enable enforcement incrementally.
-
-### What if a contract is too strict?
-
-**Contracts are configurable.** You can:
-
-- **Relax contracts:** Adjust preconditions/postconditions to match actual behavior
-- **Shadow mode:** Observe violations without blocking
-- **Warn mode:** Log violations but don't raise exceptions
-- **Block mode:** Raise exceptions on violations (default)
-
-Start in shadow mode, then tighten as you understand the code better.
-
----
-
-## Edge Case Discovery
-
-### How does CrossHair discover edge cases?
-
-**CrossHair uses symbolic execution** to explore all possible code paths mathematically. It:
-
-1. Represents inputs symbolically (not concrete values)
-2. Explores all feasible execution paths
-3. Finds inputs that violate contracts
-4. Generates concrete test cases for violations
-
-**Example:**
-
-```python
-@icontract.require(lambda numbers: len(numbers) > 0)
-@icontract.ensure(lambda numbers, result: min(numbers) > result)
-def remove_smallest(numbers: List[int]) -> int:
- smallest = min(numbers)
- numbers.remove(smallest)
- return smallest
-
-# CrossHair finds: [3, 3, 5] violates postcondition
-# (duplicates cause min(numbers) == result after removal)
-```
-
-### Can CrossHair find all edge cases?
-
-**No tool can find all edge cases**, but CrossHair is more thorough than:
-
-- Manual testing (limited by human imagination)
-- Random testing (limited by coverage)
-- LLM suggestions (probabilistic, not exhaustive)
-
-CrossHair provides **mathematical guarantees** for explored paths, but complex code may have paths that are computationally infeasible to explore.
-
-### How long does CrossHair take?
-
-**Typically 10-60 seconds per function**, depending on:
-
-- Function complexity
-- Number of code paths
-- Contract complexity
-
-For large codebases, run CrossHair on critical functions first, then expand.
-
----
-
-## Modernization Workflow
-
-### How do I start modernizing safely?
-
-**Recommended workflow:**
-
-1. **Extract specs** (`specfact code import`)
-2. **Add contracts** to 3-5 critical functions
-3. **Run CrossHair** to discover edge cases
-4. **Refactor incrementally** (one function at a time)
-5. **Verify contracts** still pass after refactoring
-6. **Expand contracts** to more functions
-
-Start in shadow mode, then enable enforcement as you gain confidence.
-
-### What if I break a contract during refactoring?
-
-**That's the point!** Contracts catch regressions immediately:
-
-```python
-# Refactored code violates contract
-process_payment(user_id=-1, amount=-50, currency="XYZ")
-
-# Contract violation caught:
-# ❌ ContractViolation: Payment amount must be positive (got -50)
-# → Fix the bug before it reaches production!
-```
-
-Contracts are your **safety net** - they prevent breaking changes from being deployed.
-
-### Can I use SpecFact with existing test suites?
-
-**Yes.** SpecFact complements existing tests:
-
-- **Tests:** Verify specific scenarios
-- **Contracts:** Enforce behavior at API boundaries
-- **CrossHair:** Discover edge cases tests miss
-
-Use all three together for comprehensive coverage.
-
-### What's the learning curve for contract-first development?
-
-**Minimal.** SpecFact is designed for incremental adoption:
-
-**Week 1 (2-4 hours):**
-
-- Run `import from-code` to extract specs (10 seconds)
-- Review extracted plan bundle
-- Add contracts to 3-5 critical functions
-
-**Week 2 (4-6 hours):**
-
-- Expand contracts to 10-15 functions
-- Run CrossHair on critical paths
-- Set up pre-commit hook
-
-**Week 3+ (ongoing):**
-
-- Add contracts incrementally as you refactor
-- Use shadow mode to observe violations
-- Enable enforcement when confident
-
-**No upfront training required.** Start with shadow mode (observe only), then enable enforcement incrementally as you understand the code better.
-
-**Resources:**
-
-- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete walkthrough
-- [Integration Showcases](../examples/integration-showcases/) - Real examples
-- [Getting Started](../getting-started/README.md) - Quick start guide
-
----
-
-## Integration
-
-### Does SpecFact work with GitHub Spec-Kit?
-
-**Yes.** SpecFact complements Spec-Kit:
-
-- **Spec-Kit:** Interactive spec authoring (greenfield)
-- **SpecFact:** Automated enforcement + brownfield support
-
-**Use both together:**
-
-1. Use Spec-Kit for initial spec generation (fast, LLM-powered)
-2. Use SpecFact to add runtime contracts to critical paths (safety net)
-3. Spec-Kit generates docs, SpecFact prevents regressions
-
-See [Spec-Kit Comparison Guide](speckit-comparison.md) for details.
-
-### Can I use SpecFact in CI/CD?
-
-**Yes.** SpecFact integrates with:
-
-- **GitHub Actions:** PR annotations, contract validation
-- **GitLab CI:** Pipeline integration
-- **Jenkins:** Plugin support (planned)
-- **Local CI:** Run `specfact govern enforce` in your pipeline
-
-Contracts can block merges if violations are detected (configurable).
-
-### Does SpecFact work with VS Code, Cursor, or other IDEs?
-
-**Yes.** SpecFact's CLI-first design means it works with **any IDE or editor**:
-
-- **VS Code:** Pre-commit hooks, tasks, or extensions
-- **Cursor:** AI assistant integration with contract validation
-- **Any editor:** Pure CLI, no IDE lock-in required
-- **Agentic workflows:** Works with any AI coding assistant
-
-**Example VS Code integration:**
-
-```bash
-# .git/hooks/pre-commit
-#!/bin/sh
-uvx specfact-cli@latest enforce stage --preset balanced
-```
-
-**Example Cursor integration:**
-
-```bash
-# Validate AI suggestions before accepting
-cursor-agent --validate-with "uvx specfact-cli@latest enforce stage"
-```
-
-See [Integration Showcases](../examples/integration-showcases/) for real examples of bugs caught via different integrations.
-
-### Do I need to learn a new platform?
-
-**No.** SpecFact is **CLI-first**—it integrates into your existing workflow:
-
-- ✅ Works with your current IDE (VS Code, Cursor, etc.)
-- ✅ Works with your current CI/CD (GitHub Actions, GitLab, etc.)
-- ✅ Works with your current tools (no new platform to learn)
-- ✅ Works offline (no cloud account required)
-- ✅ Zero vendor lock-in (OSS forever)
-
-**No platform migration needed.** Just add SpecFact CLI to your existing workflow.
-
----
-
-## Performance
-
-### How fast is code2spec extraction?
-
-**Typical timing**:
-
-- **Small codebases** (10-50 files): ~10 seconds to 1-2 minutes
-- **Medium codebases** (50-100 files): ~1-2 minutes
-- **Large codebases** (100+ files): **2-3 minutes** for AST + Semgrep analysis
-- **Large codebases with contracts** (100+ files): **15-30+ minutes** with contract extraction, graph analysis, and parallel processing (8 workers)
-
-The import process performs AST analysis, Semgrep pattern detection, and (when enabled) extracts OpenAPI contracts, relationships, and graph dependencies in parallel, which can take significant time for large repositories.
-
-### Does SpecFact require internet?
-
-**No.** SpecFact works 100% offline:
-
-- No cloud services required
-- No API keys needed
-- No telemetry (opt-in only)
-- Fully local execution
-
-Perfect for air-gapped environments or sensitive codebases.
-
----
-
-## Limitations
-
-### What are SpecFact's limitations?
-
-**Known limitations:**
-
-1. **Python-only** (JavaScript/TypeScript support planned Q1 2026)
-2. **Source code required** (not compiled bytecode)
-3. **Readable code preferred** (obfuscated code may have lower accuracy)
-4. **Complex contracts** may slow CrossHair (timeout configurable)
-
-**What SpecFact does well:**
-
-- ✅ Extracts specs from undocumented code
-- ✅ Enforces contracts at runtime
-- ✅ Discovers edge cases with symbolic execution
-- ✅ Prevents regressions during modernization
-
----
-
-## Support
-
-### Where can I get help?
-
-- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) - Ask questions
-- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) - Report bugs
-- 📧 [hello@noldai.com](mailto:hello@noldai.com) - Direct support
-
-### Can I contribute?
-
-**Yes!** SpecFact is open source. See [CONTRIBUTING.md](https://github.com/nold-ai/specfact-cli/blob/main/CONTRIBUTING.md) for guidelines.
-
----
-
-## Next Steps
-
-1. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow
-2. **[ROI Calculator](brownfield-roi.md)** - Calculate your savings
-3. **[Examples](../examples/)** - Real-world brownfield examples
-
----
+**Prerequisites:** [Installation](https://docs.specfact.io/getting-started/installation/); optional reading of the [brownfield engineer](https://modules.specfact.io/brownfield-engineer/) overview on modules.
-**Still have questions?** [Open a discussion](https://github.com/nold-ai/specfact-cli/discussions) or [email us](mailto:hello@noldai.com).
+**Full guide on the canonical modules docs site:** [Brownfield FAQ](https://modules.specfact.io/brownfield-faq/)
diff --git a/docs/guides/brownfield-journey.md b/docs/guides/brownfield-journey.md
index e87c7c42..ec4abec5 100644
--- a/docs/guides/brownfield-journey.md
+++ b/docs/guides/brownfield-journey.md
@@ -2,449 +2,15 @@
layout: default
title: Brownfield Modernization Journey
permalink: /guides/brownfield-journey/
+description: Handoff to the brownfield modernization journey on the modules documentation site.
redirect_from:
- /brownfield-journey/
---
-# Brownfield Modernization Journey
+# Brownfield modernization journey
-> **Complete step-by-step workflow for modernizing legacy Python code with SpecFact CLI**
+This guide outlines an end-to-end journey for brownfield modernization with SpecFact—from discovery through validation—so teams can migrate safely without losing behavior. Narrative, phases, and command flows are maintained alongside bundle documentation.
-**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.
+**Prerequisites:** [Quickstart](https://docs.specfact.io/getting-started/quickstart/) completed; familiarity with your repo’s layout and deployment constraints.
----
-
-## Overview
-
-This guide walks you through the complete brownfield modernization journey:
-
-1. **Understand** - Extract specs from legacy code
-2. **Protect** - Add contracts to critical paths
-3. **Discover** - Find hidden edge cases
-4. **Modernize** - Refactor safely with contract safety net
-5. **Validate** - Verify modernization success
-
-**Time investment:** 26-44 hours (vs. 220-350 hours manual)
-**ROI:** 87% time saved, $26,000-$45,000 cost avoided
-
----
-
-## Phase 1: Understand Your Legacy Code
-
-### Step 1.1: Extract Specs Automatically
-
-**CLI-First Integration**: Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. See [Integration Showcases](../examples/integration-showcases/) for real examples.
-
-```bash
-# Analyze your legacy codebase
-specfact code import legacy-api --repo ./legacy-app
-```
-
-**What happens:**
-
-- SpecFact analyzes all Python files
-- Extracts features, user stories, and business logic
-- Generates dependency graphs
-- Creates plan bundle with extracted specs
-
-**Output:**
-
-```text
-✅ Analyzed 47 Python files
-✅ Extracted 23 features
-✅ Generated 112 user stories
-⏱️ Completed in 8.2 seconds
-```
-
-**Time saved:** 60-120 hours of manual documentation → **8 seconds**
-
-**💡 Tip**: After importing, the CLI may suggest generating a bootstrap constitution for Spec-Kit integration. This auto-generates a constitution from your repository analysis. Use `specfact govern enforce sdd [BUNDLE]` for SDD enforcement when working with Spec-Kit bundles.
-
-This is especially useful if you plan to sync with Spec-Kit later.
-
-### Step 1.2: Review Extracted Specs
-
-```bash
-# Review the extracted plan using CLI commands
-specfact project snapshot legacy-api
-```
-
-**What to look for:**
-
-- High-confidence features (95%+) - These are well-understood
-- Low-confidence features (<70%) - These need manual review
-- Missing features - May indicate incomplete extraction
-- Edge cases - Already discovered by CrossHair
-
-### Step 1.3: Validate Extraction Quality
-
-```bash
-# Compare extracted plan to your understanding (bundle directory paths)
-specfact project devops-flow \
- --stage plan \
- --action compare \
- --manual .specfact/projects/manual-plan \
- --auto .specfact/projects/your-project
-```
-
-**What you get:**
-
-- Deviations between manual and auto-derived plans
-- Missing features in extraction
-- Extra features in extraction (may be undocumented functionality)
-
----
-
-## Phase 2: Protect Critical Paths
-
-### Step 2.1: Identify Critical Functions
-
-**Criteria for "critical":**
-
-- High business value (payment, authentication, data processing)
-- High risk (production bugs would be costly)
-- Complex logic (hard to understand, easy to break)
-- Frequently called (high impact if broken)
-
-**Review extracted plan:**
-
-```bash
-# Review plan using CLI commands
-specfact project snapshot legacy-api
-```
-
-### Step 2.2: Add Contracts Incrementally
-
-#### Week 1: Start with 3-5 critical functions
-
-```python
-# Example: Add contracts to payment processing
-import icontract
-
-@icontract.require(lambda amount: amount > 0, "Amount must be positive")
-@icontract.require(lambda currency: currency in ['USD', 'EUR', 'GBP'])
-@icontract.ensure(lambda result: result.status in ['SUCCESS', 'FAILED'])
-def process_payment(user_id, amount, currency):
- # Legacy code with contracts
- ...
-```
-
-#### Week 2: Expand to 10-15 functions
-
-#### Week 3: Add contracts to all public APIs
-
-#### Week 4+: Add contracts to internal functions as needed
-
-### Step 2.3: Start in Shadow Mode
-
-**Shadow mode** observes violations without blocking:
-
-```bash
-# Run in shadow mode (observe only)
-specfact govern enforce --mode shadow
-```
-
-**Benefits:**
-
-- See violations without breaking workflow
-- Understand contract behavior before enforcing
-- Build confidence gradually
-
-**Graduation path:**
-
-1. **Shadow mode** (Week 1) - Observe only
-2. **Warn mode** (Week 2) - Log violations, don't block
-3. **Block mode** (Week 3+) - Raise exceptions on violations
-
----
-
-## Phase 3: Discover Hidden Edge Cases
-
-### Step 3.1: Run CrossHair on Critical Functions
-
-```bash
-# Discover edge cases in payment processing
-hatch run contract-explore src/payment.py
-```
-
-**What CrossHair does:**
-
-- Explores all possible code paths symbolically
-- Finds inputs that violate contracts
-- Generates concrete test cases for violations
-
-**Example output:**
-
-```text
-❌ Postcondition violation found:
- Function: process_payment
- Input: amount=0.0, currency='USD'
- Issue: Amount must be positive (got 0.0)
-
-```
-
-### Step 3.2: Fix Discovered Edge Cases
-
-```python
-# Add validation for edge cases
-@icontract.require(
- lambda amount: amount > 0 and amount <= 1000000,
- "Amount must be between 0 and 1,000,000"
-)
-def process_payment(...):
- # Now handles edge cases discovered by CrossHair
- ...
-```
-
-### Step 3.3: Document Edge Cases
-
-**Keep notes on:**
-
-- Edge cases discovered
-- Contract violations found
-- Fixes applied
-- Test cases generated
-
-**Why this matters:**
-
-- Prevents regressions in future refactoring
-- Documents hidden business rules
-- Helps new team members understand code
-
----
-
-## Phase 4: Modernize Safely
-
-### Step 4.1: Refactor Incrementally
-
-**One function at a time:**
-
-1. Add contracts to function (if not already done)
-2. Run CrossHair to discover edge cases
-3. Refactor function implementation
-4. Verify contracts still pass
-5. Move to next function
-
-**Example:**
-
-```python
-# Before: Legacy implementation
-@icontract.require(lambda amount: amount > 0)
-def process_payment(user_id, amount, currency):
- # 80 lines of legacy code
- ...
-
-# After: Modernized implementation (same contracts)
-@icontract.require(lambda amount: amount > 0)
-def process_payment(user_id, amount, currency):
- # Modernized code (same contracts protect behavior)
- payment_service = PaymentService()
- return payment_service.process(user_id, amount, currency)
-```
-
-### Step 4.2: Catch Regressions Automatically
-
-**Contracts catch violations during refactoring:**
-
-```python
-# During modernization, accidentally break contract:
-process_payment(user_id=-1, amount=-50, currency="XYZ")
-
-# Runtime enforcement catches it:
-# ❌ ContractViolation: Amount must be positive (got -50)
-# → Fix the bug before it reaches production!
-
-```
-
-### Step 4.3: Verify Modernization Success
-
-```bash
-# Run contract validation
-hatch run contract-test-full
-
-# Check for violations
-specfact govern enforce --mode block
-```
-
-**Success criteria:**
-
-- ✅ All contracts pass
-- ✅ No new violations introduced
-- ✅ Edge cases still handled
-- ✅ Performance acceptable
-
----
-
-## Phase 5: Validate and Measure
-
-### Step 5.1: Measure ROI
-
-**Track metrics:**
-
-- Time saved on documentation
-- Bugs prevented during modernization
-- Edge cases discovered
-- Developer onboarding time reduction
-
-**Example metrics:**
-
-- Documentation: 87% time saved (8 hours vs. 60 hours)
-- Bugs prevented: 4 production bugs
-- Edge cases: 6 discovered automatically
-- Onboarding: 60% faster (3-5 days vs. 2-3 weeks)
-
-### Step 5.2: Document Success
-
-**Create case study:**
-
-- Problem statement
-- Solution approach
-- Quantified results
-- Lessons learned
-
-**Why this matters:**
-
-- Validates approach for future projects
-- Helps other teams learn from your experience
-- Builds confidence in brownfield modernization
-
----
-
-## Real-World Example: Complete Journey
-
-### The Problem
-
-Legacy Django app:
-
-- 47 Python files
-- No documentation
-- No type hints
-- No tests
-- 15 undocumented API endpoints
-
-### The Journey
-
-#### Week 1: Understand
-
-- Ran `specfact code import legacy-api --repo .` → 23 features extracted in 8 seconds
-- Reviewed extracted plan → Identified 5 critical features
-- Time: 2 hours (vs. 60 hours manual)
-
-#### Week 2: Protect
-
-- Added contracts to 5 critical functions
-- Started in shadow mode → Observed 3 violations
-- Time: 16 hours
-
-#### Week 3: Discover
-
-- Ran CrossHair on critical functions → Discovered 6 edge cases
-- Fixed edge cases → Added validation
-- Time: 4 hours
-
-#### Week 4: Modernize
-
-- Refactored 5 critical functions with contract safety net
-- Caught 4 regressions automatically (contracts prevented bugs)
-- Time: 24 hours
-
-#### Week 5: Validate
-
-- All contracts passing
-- No production bugs from modernization
-- New developers productive in 3 days (vs. 2-3 weeks)
-
-### The Results
-
-- ✅ **87% time saved** on documentation (8 hours vs. 60 hours)
-- ✅ **4 production bugs prevented** during modernization
-- ✅ **6 edge cases discovered** automatically
-- ✅ **60% faster onboarding** (3-5 days vs. 2-3 weeks)
-- ✅ **Zero downtime** modernization
-
-**ROI:** $42,000 saved, 5-week acceleration
-
----
-
-## Best Practices
-
-### 1. Start Small
-
-- Don't try to contract everything at once
-- Start with 3-5 critical functions
-- Expand incrementally
-
-### 2. Use Shadow Mode First
-
-- Observe violations before enforcing
-- Build confidence gradually
-- Graduate to warn → block mode
-
-### 3. Run CrossHair Early
-
-- Discover edge cases before refactoring
-- Fix issues proactively
-- Document findings
-
-### 4. Refactor Incrementally
-
-- One function at a time
-- Verify contracts after each refactor
-- Don't rush
-
-### 5. Document Everything
-
-- Edge cases discovered
-- Contract violations found
-- Fixes applied
-- Lessons learned
-
----
-
-## Common Pitfalls
-
-### ❌ Trying to Contract Everything at Once
-
-**Problem:** Overwhelming, slows down development
-
-**Solution:** Start with 3-5 critical functions, expand incrementally
-
-### ❌ Skipping Shadow Mode
-
-**Problem:** Too many violations, breaks workflow
-
-**Solution:** Always start in shadow mode, graduate gradually
-
-### ❌ Ignoring CrossHair Findings
-
-**Problem:** Edge cases discovered but not fixed
-
-**Solution:** Fix edge cases before refactoring
-
-### ❌ Refactoring Too Aggressively
-
-**Problem:** Breaking changes, contract violations
-
-**Solution:** Refactor incrementally, verify contracts after each change
-
----
-
-## Next Steps
-
-1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
-2. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete persona guide
-3. **[ROI Calculator](brownfield-roi.md)** - Calculate your savings
-4. **[Examples](../examples/)** - Real-world brownfield examples
-5. **[FAQ](brownfield-faq.md)** - More brownfield questions
-
----
-
-## Support
-
-- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
-- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
-- 📧 [hello@noldai.com](mailto:hello@noldai.com)
-
----
-
-**Happy modernizing!** 🚀
+**Full guide on the canonical modules docs site:** [Brownfield journey](https://modules.specfact.io/brownfield-journey/)
diff --git a/docs/guides/brownfield-roi.md b/docs/guides/brownfield-roi.md
index e8e3a746..5c5e1dc9 100644
--- a/docs/guides/brownfield-roi.md
+++ b/docs/guides/brownfield-roi.md
@@ -1,230 +1,14 @@
---
layout: default
-title: Brownfield Roi
+title: Brownfield ROI
permalink: /guides/brownfield-roi/
+description: Handoff to brownfield return-on-investment discussion on the modules documentation site.
---
-# Brownfield Modernization ROI with SpecFact
+# Brownfield ROI
-> **Calculate your time and cost savings when modernizing legacy Python code**
+This page summarizes how teams reason about time saved, risk reduction, and maintenance cost when adopting SpecFact on legacy codebases. Figures, assumptions, and extended discussion are maintained on the modules site.
-**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow (VS Code, Cursor, GitHub Actions, pre-commit hooks). No platform to learn, no vendor lock-in.
+**Prerequisites:** [Quickstart](https://docs.specfact.io/getting-started/quickstart/); stakeholders aligned on what “modernization” means for your product.
----
-
-## ROI Calculator
-
-Use this calculator to estimate your savings when using SpecFact CLI for brownfield modernization.
-
-### Input Your Project Size
-
-**Number of Python files in legacy codebase:** `[____]`
-**Average lines of code per file:** `[____]`
-**Hourly rate:** `$[____]` per hour
-
----
-
-## Manual Approach (Baseline)
-
-### Time Investment
-
-| Task | Time (Hours) | Cost |
-|------|-------------|------|
-| **Documentation** | | |
-| - Manually document legacy code | `[files] × 1.5-2.5 hours` | `$[____]` |
-| - Write API documentation | `[endpoints] × 2-4 hours` | `$[____]` |
-| - Create architecture diagrams | `8-16 hours` | `$[____]` |
-| **Testing** | | |
-| - Write tests for undocumented code | `[files] × 2-3 hours` | `$[____]` |
-| - Manual edge case discovery | `20-40 hours` | `$[____]` |
-| **Modernization** | | |
-| - Debug regressions during refactor | `40-80 hours` | `$[____]` |
-| - Fix production bugs from modernization | `20-60 hours` | `$[____]` |
-| **TOTAL** | **`[____]` hours** | **`$[____]`** |
-
-### Example: 50-File Legacy App
-
-| Task | Time (Hours) | Cost (@$150/hr) |
-|------|-------------|-----------------|
-| Manually document 50-file legacy app | 80-120 hours | $12,000-$18,000 |
-| Write tests for undocumented code | 100-150 hours | $15,000-$22,500 |
-| Debug regression during refactor | 40-80 hours | $6,000-$12,000 |
-| **TOTAL** | **220-350 hours** | **$33,000-$52,500** |
-
----
-
-## SpecFact Automated Approach
-
-### Time Investment (Automated)
-
-| Task | Time (Hours) | Cost |
-|------|-------------|------|
-| **Documentation** | | |
-| - Run code2spec extraction | `0.17 hours (10 min)` | `$[____]` |
-| - Review and refine extracted specs | `8-16 hours` | `$[____]` |
-| **Contract Enforcement** | | |
-| - Add contracts to critical paths | `16-24 hours` | `$[____]` |
-| - CrossHair edge case discovery | `2-4 hours` | `$[____]` |
-| **Modernization** | | |
-| - Refactor with contract safety net | `[baseline] × 0.5-0.7` | `$[____]` |
-| - Fix regressions (prevented by contracts) | `0-10 hours` | `$[____]` |
-| **TOTAL** | **`[____]` hours** | **`$[____]`** |
-
-### Example: 50-File Legacy App (Automated Results)
-
-| Task | Time (Hours) | Cost (@$150/hr) |
-|------|-------------|-----------------|
-| Run code2spec extraction | 0.17 hours (10 min) | $25 |
-| Review and refine extracted specs | 8-16 hours | $1,200-$2,400 |
-| Add contracts to critical paths | 16-24 hours | $2,400-$3,600 |
-| CrossHair edge case discovery | 2-4 hours | $300-$600 |
-| **TOTAL** | **26-44 hours** | **$3,925-$6,625** |
-
----
-
-## ROI Calculation
-
-### Time Savings
-
-**Manual approach:** `[____]` hours
-**SpecFact approach:** `[____]` hours
-**Time saved:** `[____]` hours (**`[____]%`** reduction)
-
-### Cost Savings
-
-**Manual approach:** `$[____]`
-**SpecFact approach:** `$[____]`
-**Cost avoided:** `$[____]` (**`[____]%`** reduction)
-
-### Example: 50-File Legacy App (Results)
-
-**Time saved:** 194-306 hours (**87%** reduction)
-**Cost avoided:** $26,075-$45,875 (**87%** reduction)
-
----
-
-## Industry Benchmarks
-
-### IBM GenAI Modernization Study
-
-- **70% cost reduction** via automated code discovery
-- **50% faster** feature delivery
-- **95% reduction** in manual effort
-
-### SpecFact Alignment
-
-SpecFact's code2spec provides similar automation:
-
-- **87% time saved** on documentation (vs. manual)
-- **100% detection rate** for contract violations (vs. manual review)
-- **6-12 edge cases** discovered automatically (vs. 0-2 manually)
-
----
-
-## Additional Benefits (Not Quantified)
-
-### Quality Improvements
-
-- ✅ **Zero production bugs** from modernization (contracts prevent regressions)
-- ✅ **100% API documentation** coverage (extracted automatically)
-- ✅ **Hidden edge cases** discovered before production (CrossHair)
-
-### Team Productivity
-
-- ✅ **60% faster** developer onboarding (documented codebase)
-- ✅ **50% reduction** in code review time (contracts catch issues)
-- ✅ **Zero debugging time** for contract violations (caught at runtime)
-
-### Risk Reduction
-
-- ✅ **Formal guarantees** vs. probabilistic LLM suggestions
-- ✅ **Mathematical verification** vs. manual code review
-- ✅ **Safety net** during modernization (contracts enforce behavior)
-
----
-
-## Real-World Case Studies
-
-### Case Study 1: Data Pipeline Modernization
-
-**Challenge:**
-
-- 5-year-old Python data pipeline (12K LOC)
-- No documentation, original developers left
-- Needed modernization from Python 2.7 → 3.12
-- Fear of breaking critical ETL jobs
-
-**Solution:**
-
-1. Ran `specfact code import` → 47 features extracted in 12 seconds
-2. Added contracts to 23 critical data transformation functions
-3. CrossHair discovered 6 edge cases in legacy validation logic
-4. Enforced contracts during migration, blocked 11 regressions
-5. Integrated with GitHub Actions CI/CD to prevent bad code from merging
-
-**Results:**
-
-- ✅ 87% faster documentation (8 hours vs. 60 hours manual)
-- ✅ 11 production bugs prevented during migration
-- ✅ Zero downtime migration completed in 3 weeks vs. estimated 8 weeks
-- ✅ New team members productive in days vs. weeks
-
-**ROI:** $42,000 saved, 5-week acceleration
-
-### Case Study 2: Integration Success Stories
-
-**See real examples of bugs fixed via integrations:**
-
-- **[Integration Showcases](../examples/integration-showcases/)** - 5 complete examples:
- - VS Code + Pre-commit: Async bug caught before commit
- - Cursor Integration: Regression prevented during refactoring
- - GitHub Actions: Type mismatch blocked from merging
- - Pre-commit Hook: Breaking change detected locally
- - Agentic Workflows: Edge cases discovered with symbolic execution
-
-**Key Finding**: 3 of 5 examples fully validated, showing real bugs fixed through CLI integrations.
-
----
-
-## When ROI Is Highest
-
-SpecFact provides maximum ROI for:
-
-- ✅ **Large codebases** (50+ files) - More time saved on documentation
-- ✅ **Undocumented code** - Manual documentation is most expensive
-- ✅ **High-risk systems** - Contract enforcement prevents costly production bugs
-- ✅ **Complex business logic** - CrossHair discovers edge cases manual testing misses
-- ✅ **Team modernization** - Faster onboarding = immediate productivity gains
-
----
-
-## Try It Yourself
-
-Calculate your ROI:
-
-1. **Run code2spec** on your legacy codebase:
-
- ```bash
- specfact code import legacy-api --repo ./your-legacy-app
- ```
-
-2. **Time the extraction** (typically < 10 seconds)
-
-3. **Compare to manual documentation time** (typically 1.5-2.5 hours per file)
-
-4. **Calculate your savings:**
- - Time saved = (files × 1.5 hours) - 0.17 hours
- - Cost saved = Time saved × hourly rate
-
----
-
-## Next Steps
-
-1. **[Integration Showcases](../examples/integration-showcases/)** - See real bugs fixed via VS Code, Cursor, GitHub Actions integrations
-2. **[Brownfield Engineer Guide](brownfield-engineer.md)** - Complete modernization workflow
-3. **[Brownfield Journey](brownfield-journey.md)** - Step-by-step modernization guide
-4. **[Examples](../examples/)** - Real-world brownfield examples
-
----
-
-**Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) | [hello@noldai.com](mailto:hello@noldai.com)
+**Full guide on the canonical modules docs site:** [Brownfield ROI](https://modules.specfact.io/brownfield-roi/)
diff --git a/docs/guides/contract-testing-workflow.md b/docs/guides/contract-testing-workflow.md
index 4afc3d5e..bd6908b3 100644
--- a/docs/guides/contract-testing-workflow.md
+++ b/docs/guides/contract-testing-workflow.md
@@ -2,272 +2,13 @@
layout: default
title: Contract Testing Workflow
permalink: /guides/contract-testing-workflow/
-description: Practical contract testing workflow guidance for SpecFact users and developers.
+description: Handoff to contract testing workflow on the modules documentation site.
---
-# Contract Testing Workflow - Simple Guide for Developers
+# Contract testing workflow
+Contract-first testing with SpecFact spans decorators, CrossHair, and CI layers. End-to-end workflow, troubleshooting, and alignment with `spec` commands are documented on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Contract testing layers](https://docs.specfact.io/reference/commands/) awareness; repository with public APIs you can decorate.
-## Quick Start: Verify Your Contract
-
-The easiest way to verify your OpenAPI contract works is with a single command:
-
-```bash
-# Validate a specific contract bundle
-specfact spec validate --bundle my-api --feature FEATURE-001
-
-# Validate all contracts in a bundle
-specfact spec validate --bundle my-api
-```
-
-**What this does:**
-
-1. ✅ Validates your contract schema
-2. ✅ Generates examples from the contract
-3. ✅ Starts a mock server
-4. ✅ Tests connectivity
-
-**That's it!** Your contract is verified and ready to use. The mock server keeps running so you can test your client code.
-
-## What You Can Do Without a Real API
-
-### ✅ Contract Validation (No API Needed)
-
-Use `spec validate` to ensure your contract is correct:
-
-```bash
-specfact spec validate --bundle my-api --feature FEATURE-001
-```
-
-**Output:**
-
-```
-```
-
-Step 1: Validating contracts...
-✓ FEATURE-001: Valid (13 endpoints)
-
-Step 2: Generating examples...
-✓ FEATURE-001: Examples generated
-
-Step 3: Starting mock server for FEATURE-001...
-✓ Mock server started at <http://localhost:9000>
-
-Step 4: Testing connectivity...
-✓ Health check passed: UP
-
-✓ Contract verification complete!
-
-Summary:
- • Contracts validated: 1
- • Examples generated: 1
- • Mock server: <http://localhost:9000>
-
-```
-
-### ✅ Mock Server for Development
-
-Start a mock server that generates responses from your contract:
-
-```bash
-# Start mock server with examples
-specfact spec mock --bundle my-api --feature FEATURE-001 --examples
-
-# Or use the validate command (starts mock server automatically)
-specfact spec validate --bundle my-api --feature FEATURE-001
-```
-
-**Use cases:**
-
-- Frontend development without backend
-- Client library testing
-- Integration testing (test your client against the contract)
-
-### ✅ Contract Validation
-
-Validate that your contract schema is correct:
-
-```bash
-# Validate a specific contract
-specfact spec validate --bundle my-api --feature FEATURE-001
-
-# Check test coverage across all contracts
-specfact spec generate-tests --bundle my-api
-```
-
-## Complete Workflow Examples
-
-### Example 1: New Contract Development
-
-```bash
-# 1. Set up validation for a new bundle
-specfact spec validate --bundle my-api
-
-# 2. Edit the contract file
-# Edit: .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml
-
-# 3. Validate everything works
-specfact spec validate --bundle my-api --feature FEATURE-001
-
-# 4. Test your client code against the mock server
-curl http://localhost:9000/api/endpoint
-```
-
-### Example 2: CI/CD Pipeline
-
-```bash
-# Validate contracts without starting mock server
-specfact spec validate --bundle my-api --skip-mock --no-interactive
-
-# Or just validate
-specfact spec validate --bundle my-api --no-interactive
-```
-
-### Example 3: Multiple Contracts
-
-```bash
-# Validate all contracts in a bundle
-specfact spec validate --bundle my-api
-
-# Generate tests from contracts
-specfact spec generate-tests --bundle my-api
-```
-
-## What Requires a Real API
-
-### ❌ Contract Testing Against Real Implementation
-
-The `specmatic test` command requires a **real API implementation**:
-
-```bash
-# This REQUIRES a running API
-specmatic test \
- --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \
- --host http://localhost:8000
-```
-
-**When to use:**
-
-- After implementing your API
-- To verify your implementation matches the contract
-- In integration tests
-
-**Workflow:**
-
-```bash
-# 1. Generate test files
-specfact spec generate-tests --bundle my-api --feature FEATURE-001
-
-# 2. Start your real API
-python -m uvicorn main:app --port 8000
-
-# 3. Run contract tests
-specmatic test \
- --spec .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml \
- --host http://localhost:8000
-```
-
-## Command Reference
-
-### `spec validate` - All-in-One Verification
-
-The simplest way to verify your contract:
-
-```bash
-specfact spec validate [OPTIONS]
-
-Options:
- --bundle TEXT Project bundle name
- --feature TEXT Feature key (optional - verifies all if not specified)
- --port INTEGER Port for mock server (default: 9000)
- --skip-mock Skip mock server (only validate)
- --no-interactive Non-interactive mode (CI/CD)
-```
-
-**What it does:**
-
-1. Validates contract schema
-2. Generates examples
-3. Starts mock server (unless `--skip-mock`)
-4. Tests connectivity
-
-### `spec validate` - Schema Validation
-
-```bash
-specfact spec validate --bundle my-api --feature FEATURE-001
-```
-
-Validates the OpenAPI schema structure.
-
-### `spec mock` - Mock Server
-
-```bash
-specfact spec mock --bundle my-api --feature FEATURE-001 --examples
-```
-
-Starts a mock server that generates responses from your contract.
-
-### `spec generate-tests` - Generate Tests
-
-```bash
-specfact spec generate-tests --bundle my-api --feature FEATURE-001
-```
-
-Generates test files that can be run against a real API.
-
-## Key Insights
-
-| Task | Requires Real API? | Command |
-|------|-------------------|---------|
-| **Contract Validation** | ❌ No | `spec validate` |
-| **Schema Validation** | ❌ No | `spec validate` |
-| **Mock Server** | ❌ No | `spec mock` |
-| **Example Generation** | ❌ No | `spec validate` (automatic) |
-| **Contract Testing** | ✅ Yes | `specmatic test` (after `spec generate-tests`) |
-
-## Troubleshooting
-
-### Mock Server Won't Start
-
-```bash
-# Check if Specmatic is installed
-npx specmatic --version
-
-# Install if needed
-npm install -g @specmatic/specmatic
-```
-
-### Contract Validation Fails
-
-```bash
-# Check contract file syntax
-cat .specfact/projects/my-api/contracts/FEATURE-001.openapi.yaml
-
-# Validate manually
-specfact spec validate --bundle my-api --feature FEATURE-001
-```
-
-### Examples Not Generated
-
-Examples are generated automatically from your OpenAPI schema. If generation fails:
-
-- Check that your schema has proper request/response definitions
-- Ensure data types are properly defined
-- Run `spec validate` to see detailed error messages
-
-## Best Practices
-
-1. **Start with `spec validate`** - It does everything you need
-2. **Use mock servers for development** - No need to wait for backend
-3. **Validate in CI/CD** - Use `--skip-mock --no-interactive` for fast validation
-4. **Test against real API** - Use `specmatic test` after implementation
-
-## Next Steps
-
-- Read the [API Reference](../reference/commands.md) for detailed command options
-- Check [Architecture Documentation](../architecture/overview.md) for bundle management
-- See [Agile/Scrum Workflows](../guides/agile-scrum-workflows.md) for team collaboration
+**Full guide on the canonical modules docs site:** [Contract testing workflow](https://modules.specfact.io/contract-testing-workflow/)
diff --git a/docs/guides/custom-field-mapping.md b/docs/guides/custom-field-mapping.md
index 41e29629..e4b5de92 100644
--- a/docs/guides/custom-field-mapping.md
+++ b/docs/guides/custom-field-mapping.md
@@ -2,683 +2,13 @@
layout: default
title: Custom Field Mapping Guide
permalink: /guides/custom-field-mapping/
+description: Handoff to custom field mapping on the modules documentation site.
---
-# Custom Field Mapping Guide
+# Custom field mapping
+Map tracker-specific fields to SpecFact models so refinement, import, and sync round-trip correctly. Field types, ADO/GitHub nuances, and templates are documented on the modules site.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** Tracker project access; [Authentication](https://docs.specfact.io/reference/authentication/) configured.
-> **Customize ADO field mappings** for your specific Azure DevOps process templates and agile frameworks.
-
-This guide explains how to create and use custom field mapping configurations to adapt SpecFact CLI to your organization's specific Azure DevOps field names and work item types.
-
-## Overview
-
-SpecFact CLI uses **field mappers** to normalize provider-specific field structures (GitHub markdown, ADO fields) into canonical field names that work across all providers. For Azure DevOps, you can customize these mappings to match your specific process template.
-
-### Why Custom Field Mappings?
-
-Different Azure DevOps organizations use different process templates (Scrum, SAFe, Kanban, Basic, or custom templates) with varying field names:
-
-- **Scrum**: Uses `Microsoft.VSTS.Scheduling.StoryPoints`
-- **Agile**: Uses `Microsoft.VSTS.Common.StoryPoints`
-- **Custom Templates**: May use completely different field names like `Custom.StoryPoints` or `MyCompany.Effort`
-
-Custom field mappings allow you to:
-
-- Map your organization's custom ADO fields to canonical field names
-- Support multiple agile frameworks (Scrum, SAFe, Kanban)
-- Normalize work item type names across different process templates
-- Maintain compatibility with SpecFact CLI's backlog refinement features
-- Persist required-field and constrained-value metadata for `specfact backlog add --adapter ado`
-
-## Field Mapping Template Format
-
-Field mapping files are YAML configuration files that define how ADO field names map to canonical field names.
-
-### Basic Structure
-
-```yaml
-# Framework identifier (scrum, safe, kanban, agile, default)
-framework: scrum
-
-# Field mappings: ADO field name -> canonical field name
-field_mappings:
- System.Description: description
- System.AcceptanceCriteria: acceptance_criteria
- Custom.StoryPoints: story_points
- Custom.BusinessValue: business_value
- Custom.Priority: priority
- System.WorkItemType: work_item_type
-
-# Work item type mappings: ADO work item type -> canonical work item type
-work_item_type_mappings:
- Product Backlog Item: User Story
- User Story: User Story
- Feature: Feature
- Epic: Epic
- Task: Task
- Bug: Bug
-```
-
-### Canonical Field Names
-
-All field mappings must map to these canonical field names:
-
-- **`description`**: Main description/content of the backlog item
-- **`acceptance_criteria`**: Acceptance criteria for the item
-- **`story_points`**: Story points estimate (0-100 range, Scrum/SAFe)
-- **`business_value`**: Business value estimate (0-100 range, Scrum/SAFe)
-- **`priority`**: Priority level (1-4 range, 1=highest, all frameworks)
-- **`value_points`**: Value points (SAFe-specific, calculated from business_value / story_points)
-- **`work_item_type`**: Work item type (Epic, Feature, User Story, Task, Bug, etc., framework-aware)
-
-### Field Validation Rules
-
-- **Story Points**: Must be in range 0-100 (automatically clamped)
-- **Business Value**: Must be in range 0-100 (automatically clamped)
-- **Priority**: Must be in range 1-4, where 1=highest (automatically clamped)
-- **Value Points**: Automatically calculated as `business_value / story_points` if both are present
-
-## Framework-Specific Examples
-
-### Scrum Process Template
-
-```yaml
-framework: scrum
-
-field_mappings:
- System.Description: description
- System.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
- Microsoft.VSTS.Common.BusinessValue: business_value
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
- System.IterationPath: iteration
- System.AreaPath: area
-
-work_item_type_mappings:
- Product Backlog Item: User Story
- Bug: Bug
- Task: Task
- Epic: Epic
-```
-
-### SAFe Process Template
-
-```yaml
-framework: safe
-
-field_mappings:
- System.Description: description
- System.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
- Microsoft.VSTS.Common.BusinessValue: business_value
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
- # SAFe-specific fields
- Microsoft.VSTS.Common.ValueArea: value_points
-
-work_item_type_mappings:
- Epic: Epic
- Feature: Feature
- User Story: User Story
- Task: Task
- Bug: Bug
-```
-
-### Kanban Process Template
-
-```yaml
-framework: kanban
-
-field_mappings:
- System.Description: description
- System.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
- System.State: state
- # Kanban doesn't require story points, but may have them
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
-
-work_item_type_mappings:
- User Story: User Story
- Task: Task
- Bug: Bug
- Feature: Feature
- Epic: Epic
-```
-
-### Custom Process Template
-
-```yaml
-framework: default
-
-field_mappings:
- System.Description: description
- Custom.AcceptanceCriteria: acceptance_criteria
- Custom.StoryPoints: story_points
- Custom.BusinessValue: business_value
- Custom.Priority: priority
- System.WorkItemType: work_item_type
-
-work_item_type_mappings:
- Product Backlog Item: User Story
- Requirement: User Story
- Issue: Bug
-```
-
-## Discovering Available ADO Fields
-
-Before creating custom field mappings, you need to know which fields are available in your Azure DevOps project. There are two ways to discover available fields:
-
-### Method 1: Using Mapping Command (Recommended)
-
-The easiest way to discover and map ADO fields is using `specfact backlog map-fields`.
-
-```bash
-# Interactive mapping
-specfact backlog map-fields --ado-org myorg --ado-project myproject
-
-# Automatic mapping for repeatable setup and CI
-specfact backlog map-fields \
- --provider ado \
- --ado-org myorg \
- --ado-project myproject \
- --ado-framework scrum \
- --non-interactive
-```
-
-This command will:
-
-1. Fetch all available fields from your Azure DevOps project
-2. Filter out system-only fields automatically
-3. Detect a story-like ADO work item type for create-time validation metadata
-4. Fetch required fields for that work item type
-5. Fetch constrained values for custom picklist fields and persist them for later validation
-6. Pre-populate default mappings from `AdoFieldMapper.DEFAULT_FIELD_MAPPINGS`
-7. Prefer `Microsoft.VSTS.Common.*` fields over `System.*` fields for better compatibility
-8. Use regex/fuzzy matching to suggest potential matches when no default exists
-9. In interactive mode, display an arrow-key menu with the best match pre-selected
-10. In non-interactive mode, apply deterministic mappings and fail only when required fields remain unresolved
-11. Save field mappings to `.specfact/templates/backlog/field_mappings/ado_custom.yaml`
-12. Save validation metadata to `.specfact/backlog-config.yaml`
-
-### Validation Metadata Written by `map-fields`
-
-In addition to the mapping file, the command now persists:
-
-- `selected_work_item_type`
-- `required_fields_by_work_item_type`
-- `allowed_values_by_work_item_type`
-
-`specfact backlog add --adapter ado` uses this metadata to:
-
-- reject missing required custom fields before submit
-- reject invalid picklist values before submit
-- print allowed-values hints in non-interactive mode
-
-### Non-Interactive Auto-Mapping
-
-`--non-interactive` is intended for automation and repeatable setup:
-
-- it requires explicit provider selection such as `--provider ado`
-- it auto-selects framework defaults and fuzzy matches where possible
-- it does not prompt
-- if required fields cannot be resolved automatically, it exits non-zero and tells you to rerun the command interactively
-
-**Interactive Menu Navigation:**
-
-- Use **↑** (Up arrow) and **↓** (Down arrow) to navigate through available ADO fields
-- Press **Enter** to select a field
-- The menu shows all available ADO fields in a scrollable list
-- Default mappings are pre-selected automatically
-- Fuzzy matching suggests relevant fields when no default mapping exists
-
-**Example Output:**
-
-```bash
-Fetching fields from Azure DevOps...
-✓ Loaded existing mapping from .specfact/templates/backlog/field_mappings/ado_custom.yaml
-
-Interactive Field Mapping
-Map ADO fields to canonical field names.
-
-Description (canonical: description)
- Current mapping: System.Description
-
- Available ADO fields:
- > System.Description (Description) [default - pre-selected]
- Microsoft.VSTS.Common.AcceptanceCriteria (Acceptance Criteria)
- Microsoft.VSTS.Common.StoryPoints (Story Points)
- Microsoft.VSTS.Scheduling.StoryPoints (Story Points)
- ...
- <no mapping>
-```
-
-### Method 2: Using ADO REST API
-
-You can also discover available fields directly from the Azure DevOps REST API:
-
-**Step 1: Get your Azure DevOps PAT (Personal Access Token)**
-
-- Go to: `https://dev.azure.com/{org}/_usersSettings/tokens`
-- Create a new token with "Work Items (Read)" permission
-
-**Step 2: Fetch fields using curl or HTTP client**
-
-```bash
-# Replace {org}, {project}, and {token} with your values
-curl -u ":{token}" \
- "https://dev.azure.com/{org}/{project}/_apis/wit/fields?api-version=7.1" \
- | jq '.value[] | {referenceName: .referenceName, name: .name}'
-```
-
-**Step 3: Identify field names from API response**
-
-The API returns a JSON array with field information:
-
-```json
-{
- "value": [
- {
- "referenceName": "System.Description",
- "name": "Description",
- "type": "html"
- },
- {
- "referenceName": "Microsoft.VSTS.Common.AcceptanceCriteria",
- "name": "Acceptance Criteria",
- "type": "html"
- }
- ]
-}
-```
-
-**Common ADO Field Names by Process Template:**
-
-- **Scrum**: `Microsoft.VSTS.Scheduling.StoryPoints`, `System.AcceptanceCriteria`
-- **Agile**: `Microsoft.VSTS.Common.StoryPoints`, `System.AcceptanceCriteria`
-- **SAFe**: `Microsoft.VSTS.Scheduling.StoryPoints`, `Microsoft.VSTS.Common.AcceptanceCriteria`
-- **Custom Templates**: May use `Custom.*` prefix (e.g., `Custom.StoryPoints`, `Custom.AcceptanceCriteria`)
-
-**Note**: The field `Microsoft.VSTS.Common.AcceptanceCriteria` is commonly used in many ADO process templates, while `System.AcceptanceCriteria` is less common. SpecFact CLI supports both by default and **prefers `Microsoft.VSTS.Common.*` fields over `System.*` fields** when multiple alternatives exist for better compatibility across different ADO process templates.
-
-## Using Custom Field Mappings
-
-### Method 1: Interactive Mapping Command (Recommended)
-
-Use the interactive mapping command to create and update field mappings:
-
-```bash
-specfact backlog map-fields --ado-org myorg --ado-project myproject
-```
-
-This command:
-
-- Fetches available fields from your ADO project
-- Shows current mappings (if they exist)
-- Guides you through mapping each canonical field
-- Validates the mapping before saving
-- Saves to `.specfact/templates/backlog/field_mappings/ado_custom.yaml`
-
-**Options:**
-
-- `--ado-org`: Azure DevOps organization (required)
-- `--ado-project`: Azure DevOps project (required)
-- `--ado-token`: Azure DevOps PAT (optional, uses token resolution priority: explicit > env var > stored token)
-- `--reset`: Reset custom field mapping to defaults (deletes `ado_custom.yaml` and restores default mappings)
-- `--ado-base-url`: Azure DevOps base URL (defaults to `https://dev.azure.com`)
-
-**Token Resolution:**
-
-The command automatically uses stored tokens from `specfact backlog auth azure-devops` if available. Token resolution priority:
-
-1. Explicit `--ado-token` parameter
-2. `AZURE_DEVOPS_TOKEN` environment variable
-3. Stored token via `specfact backlog auth azure-devops`
-4. Expired stored token (with warning and options to refresh)
-
-**Examples:**
-
-```bash
-# Uses stored token automatically (recommended)
-specfact backlog map-fields --ado-org myorg --ado-project myproject
-
-# Override with explicit token
-specfact backlog map-fields --ado-org myorg --ado-project myproject --ado-token your_token_here
-
-# Reset to default mappings
-specfact backlog map-fields --ado-org myorg --ado-project myproject --reset
-```
-
-**Automatic Usage:**
-
-After creating a custom mapping, it is **automatically used** by all subsequent backlog operations in that directory. No restart or additional configuration needed. The `AdoFieldMapper` automatically detects and loads `.specfact/templates/backlog/field_mappings/ado_custom.yaml` if it exists.
-
-### Method 2: CLI Parameter
-
-Use the `--custom-field-mapping` option when running the refine command:
-
-Use the `--custom-field-mapping` option when running the refine command:
-
-```bash
-specfact backlog refine ado \
- --ado-org my-org \
- --ado-project my-project \
- --custom-field-mapping /path/to/ado_custom.yaml \
- --state Active
-```
-
-The CLI will:
-
-1. Validate the file exists and is readable
-2. Validate the YAML format and schema
-3. Set it as an environment variable for the converter to use
-4. Display a success message if validation passes
-
-### Method 2: Auto-Detection
-
-Place your custom mapping file at:
-
-```bash
-.specfact/templates/backlog/field_mappings/ado_custom.yaml
-```
-
-SpecFact CLI will automatically detect and use this file if no `--custom-field-mapping` parameter is provided.
-
-### Method 3: Manually Creating Field Mapping Files
-
-You can also create field mapping files manually by editing YAML files directly.
-
-**Step 1: Create the directory structure**
-
-```bash
-mkdir -p .specfact/templates/backlog/field_mappings
-```
-
-**Step 2: Create `ado_custom.yaml` file**
-
-Create a new file `.specfact/templates/backlog/field_mappings/ado_custom.yaml` with the following structure:
-
-```yaml
-# Framework identifier (scrum, safe, kanban, agile, default)
-framework: default
-
-# Field mappings: ADO field name -> canonical field name
-field_mappings:
- System.Description: description
- Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
- Microsoft.VSTS.Common.BusinessValue: business_value
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
-
-# Work item type mappings: ADO work item type -> canonical work item type
-work_item_type_mappings:
- Product Backlog Item: User Story
- User Story: User Story
- Feature: Feature
- Epic: Epic
- Task: Task
- Bug: Bug
-```
-
-**Step 3: Validate the YAML file**
-
-Use a YAML validator or test with SpecFact CLI:
-
-```bash
-# The refine command will validate the file automatically
-specfact backlog refine ado --ado-org myorg --ado-project myproject --state Active
-```
-
-**YAML Schema Reference:**
-
-- **`framework`** (string, optional): Framework identifier (`scrum`, `safe`, `kanban`, `agile`, `default`)
-- **`field_mappings`** (dict, required): Mapping from ADO field names to canonical field names
- - Keys: ADO field reference names (e.g., `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`)
- - Values: Canonical field names (`description`, `acceptance_criteria`, `story_points`, `business_value`, `priority`, `work_item_type`)
-- **`work_item_type_mappings`** (dict, optional): Mapping from ADO work item types to canonical work item types
- - Keys: ADO work item type names (e.g., `Product Backlog Item`, `User Story`)
- - Values: Canonical work item type names (e.g., `User Story`, `Feature`, `Epic`)
-
-**Examples for Different ADO Process Templates:**
-
-**Scrum Template:**
-
-```yaml
-framework: scrum
-field_mappings:
- System.Description: description
- System.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
- Microsoft.VSTS.Common.BusinessValue: business_value
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
-```
-
-**Agile Template:**
-
-```yaml
-framework: agile
-field_mappings:
- System.Description: description
- Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
- Microsoft.VSTS.Common.BusinessValue: business_value
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
-```
-
-**SAFe Template:**
-
-```yaml
-framework: safe
-field_mappings:
- System.Description: description
- Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria
- Microsoft.VSTS.Scheduling.StoryPoints: story_points
- Microsoft.VSTS.Common.BusinessValue: business_value
- Microsoft.VSTS.Common.Priority: priority
- System.WorkItemType: work_item_type
- Microsoft.VSTS.Common.ValueArea: value_points
-```
-
-**Custom Template:**
-
-```yaml
-framework: default
-field_mappings:
- System.Description: description
- Custom.AcceptanceCriteria: acceptance_criteria
- Custom.StoryPoints: story_points
- Custom.BusinessValue: business_value
- Custom.Priority: priority
- System.WorkItemType: work_item_type
-```
-
-### Method 4: Environment Variable
-
-Set the `SPECFACT_ADO_CUSTOM_MAPPING` environment variable:
-
-```bash
-export SPECFACT_ADO_CUSTOM_MAPPING=/path/to/ado_custom.yaml
-specfact backlog refine ado --ado-org my-org --ado-project my-project
-```
-
-**Priority Order**:
-
-1. CLI parameter (`--custom-field-mapping`) - highest priority
-2. Environment variable (`SPECFACT_ADO_CUSTOM_MAPPING`)
-3. Auto-detection from `.specfact/templates/backlog/field_mappings/ado_custom.yaml` (created by `specfact init` or `specfact backlog map-fields`)
-
-## Default Field Mappings
-
-If no custom mapping is provided, SpecFact CLI uses default mappings that work with most standard ADO process templates:
-
-- `System.Description` → `description`
-- `System.AcceptanceCriteria` → `acceptance_criteria`
-- `Microsoft.VSTS.Common.AcceptanceCriteria` → `acceptance_criteria` (alternative, commonly used)
-- `Microsoft.VSTS.Common.StoryPoints` → `story_points`
-- `Microsoft.VSTS.Scheduling.StoryPoints` → `story_points` (alternative)
-- `Microsoft.VSTS.Common.BusinessValue` → `business_value`
-- `Microsoft.VSTS.Common.Priority` → `priority`
-- `System.WorkItemType` → `work_item_type`
-
-**Multiple Field Alternatives**: SpecFact CLI supports multiple ADO field names mapping to the same canonical field. For example, both `System.AcceptanceCriteria` and `Microsoft.VSTS.Common.AcceptanceCriteria` can map to `acceptance_criteria`. The mapper will check all alternatives and use the first found value.
-
-Custom mappings **override** defaults. If a field is mapped in your custom file, it will be used instead of the default.
-
-## Built-in Template Files
-
-SpecFact CLI includes built-in field mapping templates for common frameworks:
-
-- **`ado_default.yaml`**: Generic mappings for most ADO templates
-- **`ado_scrum.yaml`**: Scrum-specific mappings
-- **`ado_agile.yaml`**: Agile-specific mappings
-- **`ado_safe.yaml`**: SAFe-specific mappings
-- **`ado_kanban.yaml`**: Kanban-specific mappings
-
-These are located in `resources/templates/backlog/field_mappings/` and can be used as reference when creating your custom mappings.
-
-## Validation and Error Handling
-
-### File Validation
-
-The CLI validates custom mapping files before use:
-
-- **File Existence**: File must exist and be readable
-- **YAML Format**: File must be valid YAML
-- **Schema Validation**: File must match `FieldMappingConfig` schema (Pydantic validation)
-
-### Common Errors
-
-**File Not Found**:
-
-```bash
-Error: Custom field mapping file not found: /path/to/file.yaml
-```
-
-**Invalid YAML**:
-
-```bash
-Error: Invalid custom field mapping file: YAML parsing error
-```
-
-**Invalid Schema**:
-
-```bash
-Error: Invalid custom field mapping file: Field 'field_mappings' must be a dict
-```
-
-## Best Practices
-
-1. **Start with Defaults**: Use the built-in template files as a starting point
-2. **Test Incrementally**: Add custom mappings one at a time and test
-3. **Version Control**: Store custom mapping files in your repository
-4. **Document Custom Fields**: Document any custom ADO fields your organization uses
-5. **Framework Alignment**: Set the `framework` field to match your agile framework
-6. **Work Item Type Mapping**: Map your organization's work item types to canonical types
-
-## Integration with Backlog Refinement
-
-Custom field mappings work seamlessly with backlog refinement:
-
-1. **Field Extraction**: Custom mappings are used when extracting fields from ADO work items
-2. **Field Display**: Extracted fields (story_points, business_value, priority) are displayed in refinement output
-3. **Field Validation**: Fields are validated according to canonical field rules (0-100 for story_points, 1-4 for priority)
-4. **Writeback**: Fields are mapped back to ADO format using the same custom mappings
-
-## Troubleshooting
-
-### Fields Not Extracted
-
-If fields are not being extracted:
-
-1. **Check Field Names**: Verify the ADO field names in your mapping match exactly (case-sensitive)
- - Use `specfact backlog map-fields` to discover the exact field names in your project
- - Or use the ADO REST API to fetch available fields
-2. **Check Work Item Type**: Some fields may only exist for certain work item types
- - Test with different work item types (User Story, Feature, Epic)
-3. **Check Multiple Alternatives**: Some fields have multiple names (e.g., `System.AcceptanceCriteria` vs `Microsoft.VSTS.Common.AcceptanceCriteria`)
- - Add both alternatives to your mapping if needed
- - SpecFact CLI checks all alternatives and uses the first found value
-4. **Test with Defaults**: Try without custom mapping to see if defaults work
-5. **Check Logs**: Enable verbose logging to see field extraction details
-6. **Verify API Response**: Check the raw ADO API response to see which fields are actually present
-
-### Mapping Not Applied
-
-If your custom mapping is not being applied:
-
-1. **Check File Location**: Ensure the mapping file is in the correct location:
- - `.specfact/templates/backlog/field_mappings/ado_custom.yaml` (auto-detection)
- - Or use `--custom-field-mapping` to specify a custom path
-2. **Validate YAML Syntax**: Use a YAML validator to check syntax
- - Common issues: incorrect indentation, missing colons, invalid characters
-3. **Check File Permissions**: Ensure the file is readable
-4. **Verify Schema**: Ensure the file matches the `FieldMappingConfig` schema
- - Required: `field_mappings` (dict)
- - Optional: `framework` (string), `work_item_type_mappings` (dict)
-
-### Interactive Mapping Fails
-
-If the interactive mapping command (`specfact backlog map-fields`) fails:
-
-1. **Check Token Resolution**: The command uses token resolution priority:
- - First: Explicit `--ado-token` parameter
- - Second: `AZURE_DEVOPS_TOKEN` environment variable
- - Third: Stored token via `specfact backlog auth azure-devops`
- - Fourth: Expired stored token (shows warning with options)
-
- **Solutions:**
- - Use `--ado-token` to provide token explicitly
- - Set `AZURE_DEVOPS_TOKEN` environment variable
- - Store token: `specfact backlog auth azure-devops --pat your_pat_token`
- - Re-authenticate: `specfact backlog auth azure-devops`
-
-2. **Check ADO Connection**: Verify you can connect to Azure DevOps
- - Test with: `curl -u ":{token}" "https://dev.azure.com/{org}/{project}/_apis/wit/fields?api-version=7.1"`
-
-3. **Verify Permissions**: Ensure your PAT has "Work Items (Read)" permission
-
-4. **Check Token Expiration**: OAuth tokens expire after ~1 hour
- - Use PAT token for longer expiration (up to 1 year): `specfact backlog auth azure-devops --pat your_pat_token`
-
-5. **Verify Organization/Project**: Ensure the org and project names are correct
- - Check for typos in organization or project names
-
-6. **Check Base URL**: For Azure DevOps Server (on-premise), use `--ado-base-url` option
-
-7. **Reset to Defaults**: If mappings are corrupted, use `--reset` to restore defaults:
-
- ```bash
- specfact backlog map-fields --ado-org myorg --ado-project myproject --reset
- ```
-
-### Validation Errors
-
-If you see validation errors:
-
-1. **Check YAML Syntax**: Use a YAML validator to check syntax
-2. **Check Schema**: Ensure all required fields are present
-3. **Check Field Types**: Ensure field values match expected types (strings, integers)
-
-### Work Item Type Not Mapped
-
-If work item types are not being normalized:
-
-1. **Add to `work_item_type_mappings`**: Add your work item type to the mappings section
-2. **Check Case Sensitivity**: Work item type names are case-sensitive
-3. **Use Default**: If not mapped, the original work item type is used
-
-## Related Documentation
-
-- [Backlog Refinement Guide](./backlog-refinement.md) - Complete guide to backlog refinement
-- [ADO Adapter Documentation](../adapters/backlog-adapter-patterns.md) - ADO adapter patterns
-- [Field Mapper API Reference](../architecture/overview.md) - Technical architecture details
+**Full guide on the canonical modules docs site:** [Custom field mapping](https://modules.specfact.io/guides/custom-field-mapping/)
diff --git a/docs/guides/devops-adapter-integration.md b/docs/guides/devops-adapter-integration.md
index f3c75cbb..e1a4ac0c 100644
--- a/docs/guides/devops-adapter-integration.md
+++ b/docs/guides/devops-adapter-integration.md
@@ -2,1550 +2,13 @@
layout: default
title: DevOps Adapter Integration Guide
permalink: /guides/devops-adapter-integration/
+description: Handoff to DevOps adapter integration on the modules documentation site.
---
-# DevOps Adapter Integration Guide
+# DevOps adapter integration
+Connect SpecFact to Azure DevOps and similar systems through adapters—field mapping, sync, and automation hooks. Platform-specific setup and troubleshooting are maintained on the modules documentation site.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Authentication](https://docs.specfact.io/reference/authentication/) for your provider; adapter bundle installed where required.
-> **🆕 NEW FEATURE: Integrate SpecFact into Agile DevOps Workflows**
-> Bidirectional synchronization between OpenSpec change proposals and DevOps backlog tools enables seamless integration of specification-driven development into your existing agile workflows.
-
-This guide explains how to integrate SpecFact CLI with DevOps backlog tools (GitHub Issues, Azure DevOps, Linear, Jira) to sync OpenSpec change proposals and track implementation progress through automated comment annotations.
-
-## Policy Readiness in DevOps Flows
-
-You can validate policy readiness (DoR/DoD, Kanban flow gates, SAFe PI hooks) before posting updates back to
-your backlog system:
-
-```bash
-# Deterministic readiness validation
-specfact backlog verify-readiness --repo .
-
-# AI-assisted refinement suggestions (no automatic writes)
-specfact backlog refine --repo .
-```
-
-Both commands read `.specfact/policy.yaml`. `backlog refine` never writes changes automatically; it emits
-recommendations you can review and apply explicitly in your normal workflow.
-
-## Overview
-
-**Why This Matters**: This feature bridges the gap between specification management (OpenSpec) and backlog management (GitHub Issues, ADO, Linear, Jira), allowing you to use SpecFact's specification-driven development approach while working within your existing agile DevOps workflows.
-
-SpecFact CLI supports **bidirectional synchronization** between OpenSpec change proposals and DevOps backlog tools:
-
-- **Issue Creation**: Export OpenSpec change proposals as GitHub Issues (or other DevOps backlog items)
-- **Progress Tracking**: Automatically detect code changes and add progress comments to issues
-- **Standup Comments**: Use `specfact backlog daily --post` with `--yesterday`, `--today`, `--blockers` to post
- a standup summary as a comment on the linked issue (GitHub/ADO adapters that support comments). Standup
- config: set defaults via env (`SPECFACT_STANDUP_STATE`, `SPECFACT_STANDUP_LIMIT`,
- `SPECFACT_STANDUP_ASSIGNEE`, `SPECFACT_STANDUP_SPRINT_END`) or optional `.specfact/standup.yaml`
- (e.g. `default_state`, `limit`, `sprint`, `show_priority`, `suggest_next`). Iteration/sprint and sprint
- end date support depend on the adapter (ADO supports current iteration and iteration path; see adapter
- docs). Use `--blockers-first` and config `show_priority`/`show_value` for time-critical and value-driven
- standups. **Interactive review** (`--interactive`): step-through stories with arrow-key selection; detail
- view shows the **latest comment** and hints when older comments exist; interactive navigation includes
- **Post standup update** to post yesterday/today/blockers directly on the currently selected story.
- **Comment annotations in exports**:
- add `--comments` (alias `--annotations`) to include descriptions and comment annotations in
- `--copilot-export` and `--summarize`/`--summarize-to` outputs when the adapter supports fetching comments
- (GitHub and ADO). Use optional `--first-comments N` or `--last-comments N` to scope comment volume;
- default is full comment context. Use `--first-issues N` / `--last-issues N` and global filters
- `--search`, `--release`, `--id` for consistent backlog scope across daily/refine commands. **Value score /
- suggested next**: when BacklogItem has `story_points`, `business_value`, and `priority`, use
- `--suggest-next` or config `suggest_next` to show suggested next item (business_value / (story_points ×
- priority)). **Standup summary prompt** (`--summarize` or `--summarize-to PATH`): output a prompt
- (instruction + filter context + standup data) for slash command or Copilot to generate a standup summary.
- **Slash prompt** `specfact.backlog-daily` (or `specfact.daily`): use with IDE/Copilot for interactive
- team walkthrough story-by-story (current focus, issues/open questions, discussion notes as comments);
- the prompt is provided by the installed backlog bundle rather than the permanent core package. **Sprint goal** is stored in your
- board/sprint settings and is not displayed or edited by the CLI.
-- **Content Sanitization**: Protect internal information when syncing to public repositories
-- **Separate Repository Support**: Handle cases where OpenSpec proposals and source code are in different repositories
-
-## Supported Adapters
-
-Currently supported DevOps adapters:
-
-- **GitHub Issues** (`--adapter github`) - Full support for issue creation and progress comments
-- **Azure DevOps** (`--adapter ado`) - ✅ Available - Work item creation, status sync, progress tracking, and interactive/automatic field mapping
-- **Linear** (`--adapter linear`) - Planned
-- **Jira** (`--adapter jira`) - Planned
-
-This guide focuses on GitHub Issues integration. Azure DevOps integration follows similar patterns with ADO-specific configuration.
-
-**Azure DevOps Field Mapping**: Use `specfact backlog map-fields` to discover and map ADO fields for your specific process template. The command now supports automatic `--non-interactive` mapping, persists required fields and picklist values by work item type, and enables pre-submit validation in `specfact backlog add --adapter ado`. See [Custom Field Mapping Guide](./custom-field-mapping.md) for complete documentation.
-
-**Related**: See [Backlog Refinement Guide](../guides/backlog-refinement.md) 🆕 **NEW FEATURE** for AI-assisted template-driven refinement of backlog items with persona/framework filtering, sprint/iteration support, DoR validation, and preview/write safety.
-
----
-
-## Quick Start
-
-### 1. Create Change Proposal
-
-Create an OpenSpec change proposal in your OpenSpec repository:
-
-```bash
-# Structure: openspec/changes/<change-id>/proposal.md
-mkdir -p openspec/changes/add-feature-x
-cat > openspec/changes/add-feature-x/proposal.md << 'EOF'
-# Add Feature X
-
-## Summary
-
-Add new feature X to improve user experience.
-
-## Status
-
-- status: proposed
-
-## Implementation Plan
-
-1. Design API endpoints
-2. Implement backend logic
-3. Add frontend components
-4. Write tests
-EOF
-```
-
-### 2. Export to GitHub Issues
-
-Export the change proposal to create a GitHub issue:
-
-```bash
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --repo /path/to/openspec-repo
-```
-
-### 3. Track Code Changes
-
-As you implement the feature, track progress automatically:
-
-```bash
-# Make commits with change ID in commit message
-git commit -m "feat: implement add-feature-x - initial API design"
-
-# Track progress (detects commits and adds comments)
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --track-code-changes \
- --repo /path/to/openspec-repo \
- --code-repo /path/to/source-code-repo # If different from OpenSpec repo
-```
-
----
-
-## GitHub Issues Integration
-
-### Prerequisites
-
-**For Issue Creation:**
-
-- OpenSpec change proposals in `openspec/changes/<change-id>/proposal.md`
-- GitHub token (via `GITHUB_TOKEN` env var, `gh auth token`, or `--github-token`)
-- Repository access permissions (read for proposals, write for issues)
-
-**For Code Change Tracking:**
-
-- Issues must already exist (created via previous sync)
-- Git repository with commits mentioning the change proposal ID in commit messages
-- If OpenSpec and source code are in separate repositories, use `--code-repo` parameter
-
-### Authentication
-
-SpecFact CLI supports multiple authentication methods:
-
-> **Auth Reference**: See [Authentication](../reference/authentication.md) for device code flows, token storage, and adapter token precedence.
-
-**Option 1: Device Code (SSO-friendly)**
-
-```bash
-specfact backlog auth github
-# or use a custom OAuth app
-specfact backlog auth github --client-id YOUR_CLIENT_ID
-```
-
-**Note:** The default client ID works only for `https://github.com`. For GitHub Enterprise, provide `--client-id` or set `SPECFACT_GITHUB_CLIENT_ID`.
-
-**Option 2: GitHub CLI (Recommended)**
-
-```bash
-# Uses gh auth token automatically
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --use-gh-cli
-```
-
-**Option 3: Environment Variable**
-
-```bash
-export GITHUB_TOKEN=ghp_your_token_here
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo
-```
-
-**Option 4: Command Line Flag**
-
-```bash
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --github-token ghp_your_token_here
-```
-
-### Basic Usage
-
-#### Create Issues from Change Proposals
-
-```bash
-# Export all active proposals to GitHub Issues
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --repo /path/to/openspec-repo
-```
-
-#### Track Code Changes
-
-```bash
-# Detect code changes and add progress comments
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --track-code-changes \
- --repo /path/to/openspec-repo
-```
-
-#### Sync Specific Proposals
-
-```bash
-# Export only specific change proposals
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --change-ids add-feature-x,update-api \
- --repo /path/to/openspec-repo
-```
-
-### Project backlog context (.specfact/backlog.yaml)
-
-Store project-level adapter context (org, repo, project per adapter) so you do not have to pass `--repo-owner`, `--repo-name`, `--ado-org`, `--ado-project`, or `--ado-team` on every backlog command after authenticating once.
-
-**Resolution order**: Explicit CLI options override environment variables; environment variables override the config file. **Tokens are never read from the file**—only from CLI or env.
-
-**Config search path**: `SPECFACT_CONFIG_DIR` (if set) or `.specfact/` in the current working directory. File name: `backlog.yaml`.
-
-**File format** (YAML; optional top-level `backlog` key for nesting):
-
-```yaml
-# Optional: wrap under top-level key
-backlog:
- github:
- repo_owner: your-org
- repo_name: your-repo
- ado:
- org: your-org
- project: YourProject
- team: Your Team
-```
-
-Or without the top-level key:
-
-```yaml
-github:
- repo_owner: your-org
- repo_name: your-repo
-ado:
- org: your-org
- project: YourProject
- team: Your Team
-```
-
-**Environment variables** (override file; CLI overrides env):
-
-| Adapter | Env vars |
-|--------|----------|
-| GitHub | `SPECFACT_GITHUB_REPO_OWNER`, `SPECFACT_GITHUB_REPO_NAME` |
-| Azure DevOps | `SPECFACT_ADO_ORG`, `SPECFACT_ADO_PROJECT`, `SPECFACT_ADO_TEAM` |
-
-**Git fallback (auto-detect from clone)**:
-
-- **GitHub**: When repo is not set via CLI, env, or file, SpecFact infers `repo_owner` and `repo_name` from `git remote get-url origin` when run inside a **GitHub** clone (e.g. `https://github.com/owner/repo` or `git@github.com:owner/repo.git`). No `--repo-owner`/`--repo-name` needed when you run from the repo root.
-- **Azure DevOps**: When org/project are not set via CLI, env, or file, SpecFact infers `org` and `project` from the remote URL when run inside an **ADO** clone. Supported formats: `https://dev.azure.com/org/project/_git/repo`; SSH with keys: `git@ssh.dev.azure.com:v3/org/project/repo`; SSH without keys (other auth): `user@dev.azure.com:v3/org/project/repo` (no `ssh.` subdomain). No `--ado-org`/`--ado-project` needed when you run from the repo root.
-
-So after authenticating once, **running from the repo root is enough** for both GitHub and ADO—org/repo or org/project are detected automatically from the git remote.
-
-Applies to all backlog commands: `specfact backlog daily`, `specfact backlog refine`, `specfact project sync bridge`, etc.
-
----
-
-## When to Use `--bundle` vs Direct Export
-
-> **⚠️ Important**: Understanding when to use `--bundle` is crucial for successful exports. Using `--bundle` incorrectly will result in "0 backlog items exported" errors.
-
-### Direct Export (No `--bundle`) - Most Common Use Case ✅
-
-**Use this for**: Exporting OpenSpec change proposals directly to GitHub/ADO from your `openspec/changes/` directory.
-
-**How it works**: Reads proposals directly from `openspec/changes/<change-id>/proposal.md` files.
-
-**Example**:
-
-```bash
-# ✅ CORRECT: Direct export from OpenSpec to GitHub
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --change-ids add-feature-x \
- --repo /path/to/openspec-repo
-```
-
-**When to use**:
-
-- ✅ Exporting OpenSpec change proposals to backlog tools (GitHub, ADO)
-- ✅ First-time export of a change proposal
-- ✅ Updating existing issues from OpenSpec proposals
-- ✅ Most common workflow for OpenSpec → GitHub/ADO sync
-
-**What happens**:
-
-1. Reads `openspec/changes/<change-id>/proposal.md`
-2. Creates/updates GitHub issue or ADO work item
-3. Updates `source_tracking` in proposal.md with issue/work item ID
-
-### Bundle Export (With `--bundle`) - Cross-Adapter Sync Only 🚀
-
-**Use this for**: Migrating backlog items between different adapters (GitHub → ADO, ADO → GitHub) with lossless content preservation.
-
-**How it works**: Exports from stored bundle content (not from OpenSpec directly). Requires proposals to be imported into bundle first.
-
-**Example**:
-
-```bash
-# Step 1: Import GitHub issue into bundle (stores lossless content)
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner your-org --repo-name your-repo \
- --bundle migration-bundle \
- --backlog-ids 123
-
-# Output: "✓ Imported GitHub issue #123 as change proposal: add-feature-x"
-# Note the change_id from output
-
-# Step 2: Export from bundle to ADO (uses stored content)
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org --ado-project your-project \
- --bundle migration-bundle \
- --change-ids add-feature-x # Use change_id from Step 1
-```
-
-**When to use**:
-
-- ✅ Cross-adapter sync (GitHub → ADO, ADO → GitHub)
-- ✅ Migrating backlog items between tools
-- ✅ Preserving lossless content during migrations
-- ✅ Multi-tool workflows (public GitHub + internal ADO)
-
-**What happens**:
-
-1. **Step 1 (Import)**: Fetches backlog item, stores raw content in bundle, creates proposal
-2. **Step 2 (Export)**: Loads proposal from bundle, uses stored raw content, creates new backlog item
-
-### Common Mistake: Using `--bundle` for Direct Export ❌
-
-**Problem**: Using `--bundle` when exporting directly from OpenSpec:
-
-```bash
-# ❌ WRONG: This will show "0 backlog items exported"
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name your-repo \
- --bundle some-bundle \
- --change-ids add-feature-x \
- --repo /path/to/openspec-repo
-```
-
-**Why it fails**: With `--bundle`, the system looks for proposals in the bundle's `change_tracking.proposals`, not in `openspec/changes/`. If the bundle doesn't have the proposal (because it was never imported), you get "0 backlog items exported".
-
-**Solution**: Remove `--bundle` for direct OpenSpec exports:
-
-```bash
-# ✅ CORRECT: Direct export (no --bundle)
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name your-repo \
- --change-ids add-feature-x \
- --repo /path/to/openspec-repo
-```
-
-### Quick Decision Guide
-
-| Scenario | Use `--bundle`? | Command Pattern |
-|----------|----------------|-----------------|
-| Export OpenSpec proposal → GitHub | ❌ No | `--adapter github --mode export-only --change-ids <id> --repo <openspec-repo>` |
-| Export OpenSpec proposal → ADO | ❌ No | `--adapter ado --mode export-only --change-ids <id> --repo <openspec-repo>` |
-| Import GitHub issue → Bundle → Export to ADO | ✅ Yes | Step 1: `--bundle <name> --backlog-ids <id>`<br>Step 2: `--bundle <name> --change-ids <id>` |
-| Migrate ADO work item → GitHub | ✅ Yes | Step 1: `--bundle <name> --backlog-ids <id>`<br>Step 2: `--bundle <name> --change-ids <id>` |
-
-### Summary
-
-- **Direct Export** (no `--bundle`): OpenSpec → GitHub/ADO - reads from `openspec/changes/` directly
-- **Bundle Export** (with `--bundle`): Cross-adapter sync only - exports from stored bundle content
-- **Rule of thumb**: Only use `--bundle` when migrating between different backlog adapters
-
----
-
-## Separate OpenSpec and Source Code Repositories
-
-When your OpenSpec change proposals are in a different repository than your source code:
-
-### Architecture
-
-- **OpenSpec Repository** (`--repo`): Contains change proposals in `openspec/changes/` directory
-- **Source Code Repository** (`--code-repo`): Contains actual implementation commits
-
-### Example Setup
-
-```bash
-# OpenSpec proposals in specfact-cli-internal
-# Source code in specfact-cli
-
-# Step 1: Create issue from proposal
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner nold-ai \
- --repo-name specfact-cli-internal \
- --repo /path/to/specfact-cli-internal
-
-# Step 2: Track code changes from source code repo
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner nold-ai \
- --repo-name specfact-cli-internal \
- --track-code-changes \
- --repo /path/to/specfact-cli-internal \
- --code-repo /path/to/specfact-cli
-```
-
-### Why Use `--code-repo`?
-
-- **OpenSpec repository** (`--repo`): Contains change proposals and tracks issue metadata
-- **Source code repository** (`--code-repo`): Contains actual implementation commits that reference the change proposal ID
-
-If both are in the same repository, you can omit `--code-repo` and it will use `--repo` for both purposes.
-
----
-
-## Content Sanitization
-
-When exporting to public repositories, use content sanitization to protect internal information:
-
-### What Gets Sanitized
-
-**Removed:**
-
-- Competitive analysis sections
-- Market positioning statements
-- Implementation details (file-by-file changes)
-- Effort estimates and timelines
-- Technical architecture details
-- Internal strategy sections
-
-**Preserved:**
-
-- High-level feature descriptions
-- User-facing value propositions
-- Acceptance criteria
-- External documentation links
-- Use cases and examples
-
-### Usage
-
-```bash
-# Public repository: sanitize content
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name public-repo \
- --sanitize \
- --target-repo your-org/public-repo \
- --repo /path/to/openspec-repo
-
-# Internal repository: use full content
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name internal-repo \
- --no-sanitize \
- --target-repo your-org/internal-repo \
- --repo /path/to/openspec-repo
-```
-
-### Auto-Detection
-
-SpecFact CLI automatically detects when to sanitize:
-
-- **Different repos** (code repo ≠ planning repo): Sanitization recommended (default: yes)
-- **Same repo** (code repo = planning repo): Sanitization optional (default: no)
-
-You can override with `--sanitize` or `--no-sanitize` flags.
-
----
-
-## Code Change Tracking
-
-### How It Works
-
-When `--track-code-changes` is enabled:
-
-1. **Repository Selection**: Uses `--code-repo` if provided, otherwise uses `--repo`
-2. **Git Commit Detection**: Searches git log for commits mentioning the change proposal ID
-3. **File Change Tracking**: Extracts files modified in detected commits
-4. **Progress Comment Generation**: Formats comment with commit details and file changes
-5. **Duplicate Prevention**: Checks against existing comments to avoid duplicates
-6. **Source Tracking Update**: Updates `proposal.md` with progress metadata
-
-### Commit Message Format
-
-Include the change proposal ID in your commit messages:
-
-```bash
-# Good: Change ID clearly mentioned
-git commit -m "feat: implement add-feature-x - initial API design"
-git commit -m "fix: add-feature-x - resolve authentication issue"
-git commit -m "docs: add-feature-x - update API documentation"
-
-# Also works: Change ID anywhere in message
-git commit -m "Implement new feature
-
-- Add API endpoints
-- Update database schema
-- Related to add-feature-x"
-```
-
-### Progress Comment Format
-
-Progress comments include:
-
-- **Commit details**: Hash, message, author, date
-- **Files changed**: Up to 10 files listed, then "and X more file(s)"
-- **Detection timestamp**: When the change was detected
-
-**Example Comment:**
-
-```
-📊 **Code Change Detected**
-
-**Commit**: `364c8cfb` - feat: implement add-feature-x - initial API design
-**Author**: @username
-**Date**: 2025-12-30
-**Files Changed**:
-- src/api/endpoints.py
-- src/models/feature.py
-- tests/test_feature.py
-- and 2 more file(s)
-
-*Detected at: 2025-12-30T10:00:00Z*
-```
-
-### Progress Comment Sanitization
-
-When `--sanitize` is enabled, progress comments are sanitized:
-
-- **Commit messages**: Internal keywords removed, long messages truncated
-- **File paths**: Replaced with file type counts (e.g., "3 py file(s)")
-- **Author emails**: Removed, only username shown
-- **Timestamps**: Date only (no time component)
-
----
-
-## Integration Workflow
-
-### Initial Setup (One-Time)
-
-1. **Create Change Proposal**:
-
- ```bash
- mkdir -p openspec/changes/add-feature-x
- # Edit openspec/changes/add-feature-x/proposal.md
- ```
-
-2. **Export to GitHub**:
-
- ```bash
- specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --repo /path/to/openspec-repo
- ```
-
-3. **Verify Issue Created**:
-
- ```bash
- gh issue list --repo your-org/your-repo
- ```
-
-### Development Workflow (Ongoing)
-
-1. **Make Commits** with change ID in commit message:
-
- ```bash
- git commit -m "feat: implement add-feature-x - initial API design"
- ```
-
-2. **Track Progress**:
-
- ```bash
- specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --track-code-changes \
- --repo /path/to/openspec-repo \
- --code-repo /path/to/source-code-repo
- ```
-
-3. **Verify Comments Added**:
-
- ```bash
- gh issue view <issue-number> --repo your-org/your-repo --json comments
- ```
-
-### Manual Progress Updates
-
-Add manual progress comments without code change detection:
-
-```bash
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --add-progress-comment \
- --repo /path/to/openspec-repo
-```
-
----
-
-## Advanced Features
-
-### Beyond Export/Update Capabilities
-
-SpecFact supports more than exporting and updating backlog items:
-
-- **Selective backlog import into bundles**: Import only the issues/work items you select (no bulk import by default).
- - Use `--mode bidirectional` with `--backlog-ids` or `--backlog-ids-file` and `--bundle`.
-- **Status synchronization**: Keep OpenSpec/bundle proposal status aligned with backlog item state.
-- **Validation reporting**: Attach validation outcomes (e.g., contract checks) as backlog comments when enabled.
-- **Progress notes**: Add progress updates via `--track-code-changes` or `--add-progress-comment`.
-- **Cross-adapter export**: Export stored bundle content 1:1 to another backlog adapter (GitHub ↔ ADO) with `--bundle`.
-
-Example: Import selected GitHub issues into a bundle and keep them in sync:
-
-```bash
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner your-org --repo-name your-repo \
- --bundle main \
- --backlog-ids 111,112
-```
-
-### Cross-Adapter Sync: Lossless Round-Trip Migration
-
-> **🚀 Advanced Feature**: One of SpecFact's most powerful capabilities for DevOps teams working with multiple backlog tools.
-
-SpecFact enables **lossless round-trip synchronization** between different backlog adapters (GitHub ↔ Azure DevOps ↔ others), allowing you to:
-
-- **Migrate between backlog tools** without losing content or metadata
-- **Sync across teams** using different tools (e.g., GitHub for open source, ADO for enterprise)
-- **Maintain consistency** when working with multiple backlog systems
-- **Preserve full content fidelity** across adapter boundaries
-
-#### How It Works
-
-The system uses **lossless content preservation** to ensure 100% fidelity during cross-adapter syncs:
-
-1. **Content Storage**: When importing from any backlog adapter, the original raw content (title, body, metadata) is stored in the project bundle's `source_tracking` metadata
-2. **Bundle Export**: Export from stored bundles preserves the original content exactly as it was imported
-3. **Round-Trip Safety**: Content can be synced GitHub → OpenSpec → ADO → OpenSpec → GitHub with no data loss
-
-#### Example: GitHub → ADO Migration
-
-Migrate a GitHub issue to Azure DevOps while preserving all content:
-
-**Step-by-Step Guide:**
-
-```bash
-# Step 1: Import GitHub issue into bundle (stores lossless content)
-# This creates a change proposal in the bundle and stores raw content
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner your-org --repo-name your-repo \
- --bundle main \
- --backlog-ids 123
-
-# After Step 1, the CLI will show the change_id that was created
-# Example output: "✓ Imported GitHub issue #123 as change proposal: add-feature-x"
-# Note the change_id from the output (e.g., "add-feature-x")
-
-# Step 2: Find the change_id (if you missed it in the output)
-# Option A: Check the bundle directory
-ls .specfact/projects/main/change_tracking/proposals/
-# Lists all proposal files - the filename is the change_id
-
-# Option B: Check OpenSpec changes directory (if external_base_path is set)
-ls /path/to/openspec-repo/openspec/changes/
-# Lists all change directories - the directory name is the change_id
-
-# Step 3: Export from bundle to ADO (uses stored lossless content)
-# Replace <change-id> with the actual change_id from Step 1
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org --ado-project your-project \
- --bundle main \
- --change-ids add-feature-x # Use the actual change_id from Step 1
-
-# Step 4: Verify the export worked
-# The CLI will show: "✓ Exported to ADO" with work item ID and URL
-# Example: "✓ Work item created: https://dev.azure.com/your-org/your-project/_workitems/edit/456"
-```
-
-**What Happens Behind the Scenes:**
-
-1. **Step 1 (Import)**:
- - Fetches GitHub issue #123
- - Creates change proposal in bundle `main`
- - Stores raw content (title, body) in `source_tracking.source_metadata`
- - Creates OpenSpec proposal in `openspec/changes/<change-id>/proposal.md`
- - Returns change_id (e.g., `add-feature-x`)
-
-2. **Step 3 (Export)**:
- - Loads proposal from bundle `main`
- - Uses stored raw content (not reconstructed from sections)
- - Creates ADO work item with exact same content
- - Stores ADO work item ID in `source_tracking` for future updates
-
-**Finding the Change ID:**
-
-The change_id is derived from the GitHub issue:
-
-- **If issue has OpenSpec footer**: Uses the change_id from footer (e.g., `*OpenSpec Change Proposal:`add-feature-x`*`)
-- **If no footer**: Uses issue number as change_id (e.g., `123`)
-
-**Verification:**
-
-After export, verify content matches:
-
-```bash
-# Check the exported ADO work item
-# Visit the work item URL shown in Step 4 output
-# Compare content with original GitHub issue
-# Both should have identical content (Why, What Changes sections)
-```
-
-The exported ADO work item will contain the exact same content as the original GitHub issue, including:
-
-- Full markdown formatting
-- All sections (Why, What Changes, etc.)
-- Metadata and source tracking
-- Status and labels (mapped appropriately)
-
-#### Example: Multi-Tool Sync Workflow
-
-Keep proposals in sync across GitHub (public) and ADO (internal):
-
-**Complete Workflow with Change IDs:**
-
-```bash
-# Day 1: Create proposal in OpenSpec, export to GitHub (public)
-# Assume change_id is "add-feature-x" (from openspec/changes/add-feature-x/proposal.md)
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name public-repo \
- --sanitize \
- --repo /path/to/openspec-repo \
- --change-ids add-feature-x
-
-# Output shows: "✓ Exported to GitHub" with issue number (e.g., #123)
-# Note the GitHub issue number: 123
-
-# Day 2: Import GitHub issue into bundle (for internal team)
-# This stores lossless content in the bundle
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner your-org --repo-name public-repo \
- --bundle internal \
- --backlog-ids 123
-
-# Output shows: "✓ Imported GitHub issue #123 as change proposal: add-feature-x"
-# Note the change_id: add-feature-x
-
-# Day 3: Export to ADO for internal tracking (full content, no sanitization)
-# Uses the change_id from Day 2
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org --ado-project internal-project \
- --bundle internal \
- --change-ids add-feature-x
-
-# Output shows: "✓ Exported to ADO" with work item ID (e.g., 456)
-# Note the ADO work item ID: 456
-
-# Day 4: Update in ADO, sync back to GitHub (status sync)
-# Import ADO work item to update bundle with latest status
-specfact project sync bridge --adapter ado --mode bidirectional \
- --ado-org your-org --ado-project internal-project \
- --bundle internal \
- --backlog-ids 456
-
-# Output shows: "✓ Imported ADO work item #456 as change proposal: add-feature-x"
-# Bundle now has latest status from ADO
-
-# Then sync status back to GitHub
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name public-repo \
- --update-existing \
- --repo /path/to/openspec-repo \
- --change-ids add-feature-x
-
-# Output shows: "✓ Updated GitHub issue #123"
-```
-
-**Key Points:**
-
-- **Change IDs are consistent**: The same change_id (`add-feature-x`) is used across all adapters
-- **Bundle preserves content**: The `internal` bundle stores lossless content from GitHub, which is then exported to ADO
-- **Status sync**: Bidirectional sync updates the bundle, then export-only syncs status to other adapters
-- **No content loss**: Raw content stored in bundle ensures 100% fidelity across all syncs
-
-#### Lossless Content Preservation
-
-SpecFact ensures **zero data loss** during cross-adapter syncs by:
-
-- **Storing raw content**: Original title and body stored in `source_tracking.source_metadata.raw_title` and `raw_body`
-- **Preserving formatting**: Markdown formatting, sections, and structure maintained exactly
-- **Metadata preservation**: Source tracking, timestamps, and adapter-specific metadata preserved
-- **Round-trip validation**: Content can be verified to match original after multiple sync cycles
-
-#### Use Cases
-
-**1. Tool Migration**
-
-- Migrate from GitHub Issues to Azure DevOps without losing any content
-- Move from ADO to GitHub for open source projects
-- Transition between backlog tools as team needs change
-
-**2. Multi-Tool Workflows**
-
-- Public GitHub issues (sanitized) + Internal ADO work items (full content)
-- Open source tracking (GitHub) + Enterprise tracking (ADO)
-- Cross-team collaboration with different tool preferences
-
-**3. Feature Branch Integration**
-
-- Sync proposals with feature branches across different backlog tools
-- Track code changes in one tool, sync status to another
-- Maintain consistency when teams use different tools
-
-**4. Validation & Code Change Tracking**
-
-- Attach validation results to backlog items in any adapter
-- Track code changes across multiple backlog systems
-- Maintain audit trail across tool boundaries
-
-#### Step-by-Step: Complete Cross-Adapter Sync Workflow
-
-**Scenario**: Migrate a GitHub issue to Azure DevOps with full content preservation.
-
-```bash
-# Prerequisites: Set up authentication
-export GITHUB_TOKEN='your-github-token'
-export AZURE_DEVOPS_TOKEN='your-ado-token'
-
-# Step 1: Import GitHub issue into bundle
-# This stores the issue in a bundle with lossless content preservation
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner your-org --repo-name your-repo \
- --bundle migration-bundle \
- --backlog-ids 123
-
-# Expected output:
-# ✓ Imported GitHub issue #123 as change proposal: add-feature-x
-# Note the change_id: "add-feature-x"
-
-# Step 2: Verify the import (optional but recommended)
-# Check that the proposal was created in the bundle
-ls .specfact/projects/migration-bundle/change_tracking/proposals/
-# Should show: add-feature-x.yaml (or similar)
-
-# Step 3: Export to Azure DevOps
-# Use the change_id from Step 1
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org --ado-project your-project \
- --bundle migration-bundle \
- --change-ids add-feature-x
-
-# Expected output:
-# ✓ Exported to ADO
-# ✓ Work item created: https://dev.azure.com/your-org/your-project/_workitems/edit/456
-# Note the work item ID: 456
-
-# Step 4: Verify content preservation
-# Visit the ADO work item URL and compare with original GitHub issue
-# Content should match exactly (Why, What Changes sections, formatting)
-
-# Step 5: Optional - Round-trip back to GitHub to verify
-specfact project sync bridge --adapter ado --mode bidirectional \
- --ado-org your-org --ado-project your-project \
- --bundle migration-bundle \
- --backlog-ids 456
-
-# Then export back to GitHub
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name your-repo \
- --bundle migration-bundle \
- --change-ids add-feature-x \
- --update-existing
-
-# Verify GitHub issue content matches original
-```
-
-#### Complete Round-Trip Example: GitHub → ADO → GitHub
-
-**Scenario**: Full bidirectional sync workflow demonstrating lossless content preservation across GitHub and Azure DevOps.
-
-This example demonstrates the complete cross-adapter sync workflow, showing how to:
-
-1. Import a GitHub issue into a bundle
-2. Export to Azure DevOps
-3. Import back from Azure DevOps
-4. Export back to GitHub
-5. Verify content preservation throughout
-
-```bash
-# Prerequisites: Set up authentication
-export GITHUB_TOKEN='your-github-token'
-export AZURE_DEVOPS_TOKEN='your-ado-token'
-
-# ============================================================
-# STEP 1: Import GitHub Issue → SpecFact Bundle
-# ============================================================
-# Import GitHub issue #110 into bundle 'cross-sync-test'
-# Note: Bundle will be auto-created if it doesn't exist
-# This stores lossless content in the bundle
-specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner nold-ai --repo-name specfact-cli \
- --bundle cross-sync-test \
- --backlog-ids 110
-
-# Expected output:
-# ✓ Imported GitHub issue #110 as change proposal: <change-id>
-# Note the change_id from output (e.g., "add-ado-backlog-adapter" or "110")
-
-# Find change_id if you missed it:
-# Option A: Check bundle directory
-ls .specfact/projects/cross-sync-test/change_tracking/proposals/
-
-# Option B: Check OpenSpec directory (if using external repo)
-ls /path/to/openspec-repo/openspec/changes/
-
-# ============================================================
-# STEP 2: Export SpecFact Bundle → Azure DevOps
-# ============================================================
-# Export the proposal to ADO using the change_id from Step 1
-# Replace <change-id> with the actual change_id from Step 1
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org --ado-project your-project \
- --bundle cross-sync-test \
- --change-ids <change-id>
-
-# Expected output:
-# ✓ Exported to ADO
-# ✓ Exported 1 backlog item(s)
-# Note the ADO work item ID from the output (e.g., 456)
-
-# ============================================================
-# STEP 3: Import Azure DevOps → SpecFact Bundle
-# ============================================================
-# Import the ADO work item back into the bundle
-# This updates the bundle with ADO's version of the content
-# Replace <ado-work-item-id> with the ID from Step 2
-specfact project sync bridge --adapter ado --mode bidirectional \
- --ado-org your-org --ado-project your-project \
- --bundle cross-sync-test \
- --backlog-ids <ado-work-item-id>
-
-# Expected output:
-# ✓ Imported ADO work item #<ado-work-item-id> as change proposal: <change-id>
-# The change_id should match the one from Step 1
-
-# ============================================================
-# STEP 4: Export SpecFact Bundle → GitHub (Round-Trip)
-# ============================================================
-# Export back to GitHub to complete the round-trip
-# This updates the original GitHub issue with any changes from ADO
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner nold-ai --repo-name specfact-cli \
- --bundle cross-sync-test \
- --change-ids <change-id> \
- --update-existing
-
-# Expected output:
-# ✓ Exported to GitHub
-# ✓ Updated GitHub issue #110
-
-# ============================================================
-# STEP 5: Verification
-# ============================================================
-# Verify content preservation:
-# 1. Visit the original GitHub issue: https://github.com/nold-ai/specfact-cli/issues/110
-# 2. Visit the ADO work item URL from Step 2
-# 3. Compare content - both should have identical:
-# - Why section
-# - What Changes section
-# - Formatting and structure
-# - Metadata (status, labels mapped appropriately)
-```
-
-**What This Demonstrates:**
-
-- **Lossless Content Preservation**: Content is preserved exactly through GitHub → ADO → GitHub round-trip
-- **Bundle as Storage**: The bundle stores raw content, ensuring 100% fidelity
-- **Bidirectional Sync**: Both adapters can import and export, maintaining consistency
-- **Change ID Consistency**: The same change_id is used across all adapters
-- **Status Synchronization**: Status changes in one adapter are reflected in others
-
-**Key Points:**
-
-- **Bundle is required**: Without `--bundle`, content may be reconstructed and lose formatting
-- **Change IDs are persistent**: The same change_id is used throughout the workflow
-- **Content verification**: Always verify content matches after each step
-- **Update existing**: Use `--update-existing` when exporting back to GitHub to update the original issue
-
-**Important Notes:**
-
-- **Bundle is required**: Without `--bundle`, content is reconstructed from sections (may lose formatting)
-- **Change IDs**: The change_id is shown in the import output, or check the bundle directory
-- **Work Item IDs**: ADO work item IDs are shown in export output, or check `source_tracking` in proposal.md
-- **Content verification**: Always verify content matches after cross-adapter sync
-
-#### Best Practices
-
-- **Use bundles for cross-adapter sync**: Always use `--bundle` when syncing between adapters to preserve lossless content
-- **Verify content preservation**: After cross-adapter sync, verify content matches original
-- **Handle sanitization carefully**: Public repos may need sanitization, internal repos can use full content
-- **Track source origins**: Use `source_tracking` metadata to understand where content originated
-- **Test round-trips**: Validate lossless sync by syncing back to original adapter and comparing content
-- **Note change IDs**: Save change IDs from import output for use in export commands
-- **Check bundle contents**: Use `ls .specfact/projects/<bundle-name>/change_tracking/proposals/` to list all proposals in a bundle
-
-### Update Existing Issues
-
-When a change proposal already has a linked GitHub issue (via `source_tracking` metadata in the proposal), you can update the issue with the latest proposal content.
-
-#### Prerequisites
-
-The change proposal must have `source_tracking` metadata linking it to the GitHub issue. This is automatically added when:
-
-- You first export a proposal to create an issue
-- You import an existing issue as a change proposal (using bidirectional sync)
-- You manually add it to the proposal's `proposal.md` file
-
-**Example `source_tracking` in `proposal.md`:**
-
-```markdown
-## Source Tracking
-
-- **GitHub Issue**: #105
-- **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/105>
-- **Repository**: nold-ai/specfact-cli
-- **Last Synced Status**: proposed
-<!-- content_hash: e628d8468669ebfc -->
-```
-
-#### Update a Specific Issue
-
-To update a specific change proposal's linked issue:
-
-```bash
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --change-ids your-change-id \
- --update-existing \
- --repo /path/to/openspec-repo
-```
-
-**Example: Update issue #105 for change proposal `implement-adapter-enhancement-recommendations`:**
-
-```bash
-cd /path/to/openspec-repo
-
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner nold-ai \
- --repo-name specfact-cli \
- --change-ids implement-adapter-enhancement-recommendations \
- --update-existing \
- --repo .
-```
-
-#### Update All Linked Issues
-
-To update all change proposals that have linked GitHub issues:
-
-```bash
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --update-existing \
- --repo /path/to/openspec-repo
-```
-
-#### What Gets Updated
-
-When `--update-existing` is used, the GitHub adapter will:
-
-1. **Read `source_tracking` metadata** from the change proposal to find the linked issue number
-2. **Compare content hash** to detect if the proposal has changed since last sync
-3. **Update issue body** with the latest proposal content (if content changed)
-4. **Update issue title** if the proposal title changed
-5. **Sync status labels** (OpenSpec status ↔ GitHub labels)
-6. **Add/update OpenSpec metadata footer** in the issue body
-
-#### Content Hash Detection
-
-The adapter uses a content hash to detect changes. The hash is stored in the proposal's `source_tracking` section:
-
-```markdown
-<!-- content_hash: e628d8468669ebfc -->
-```
-
-If the proposal content hasn't changed, the issue won't be updated (even with `--update-existing`), preventing unnecessary API calls.
-
-#### Best Practices
-
-- **Use `--change-ids`** to update specific proposals instead of all proposals
-- **Use `--update-existing` sparingly** (only when proposal content changes significantly)
-- **Verify before updating** by checking the proposal's `source_tracking` metadata
-- **Review changes** in the proposal before syncing to ensure accuracy
-
-### Updating Archived Change Proposals
-
-When you improve comment logic or branch detection algorithms, you may want to update existing GitHub issues for archived change proposals with the new improvements.
-
-#### Use Case
-
-- **New comment logic**: When you add new features to status comments (e.g., branch detection improvements)
-- **Branch detection improvements**: When you enhance branch detection algorithms
-- **Comment format updates**: When you change how comments are formatted
-
-#### How It Works
-
-By default, archived change proposals (in `openspec/changes/archive/`) are excluded from sync. Use `--include-archived` to include them:
-
-```bash
-# Update all archived proposals with new comment logic
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --include-archived \
- --update-existing \
- --repo /path/to/openspec-repo
-
-# Update specific archived proposal
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org \
- --repo-name your-repo \
- --change-ids add-code-change-tracking \
- --include-archived \
- --update-existing \
- --repo /path/to/openspec-repo
-```
-
-#### What Gets Updated
-
-When `--include-archived` is used with `--update-existing`:
-
-1. **Archived proposals are included** in the sync (normally excluded)
-2. **Comments are always updated** for applied status (even if content hash hasn't changed)
-3. **Branch detection runs** with the latest improvements
-4. **Issue state is verified** and updated if needed
-
-#### Example: Updating Issue #107
-
-```bash
-# Update issue #107 with improved branch detection
-specfact project sync bridge --adapter github --mode export-only \
- --repo-owner nold-ai \
- --repo-name specfact-cli \
- --change-ids add-code-change-tracking \
- --include-archived \
- --update-existing \
- --repo /path/to/specfact-cli-internal
-```
-
-This will:
-
-- Find the archived proposal `add-code-change-tracking` in `openspec/changes/archive/`
-- Detect the implementation branch using the latest branch detection logic
-- Add/update a comment on issue #107 with the correct branch information
-
-### Proposal Filtering
-
-Proposals are filtered based on target repository type:
-
-**Public Repositories** (with `--sanitize`):
-
-- Only syncs proposals with status `"applied"` (archived/completed changes)
-- Filters out `"proposed"`, `"in-progress"`, `"deprecated"`, or `"discarded"`
-
-**Internal Repositories** (with `--no-sanitize`):
-
-- Syncs all active proposals regardless of status
-
-### Duplicate Prevention
-
-Progress comments are deduplicated using SHA-256 hash:
-
-- First run: Comment added
-- Second run: Comment skipped (duplicate detected)
-- New commits: New comment added
-
----
-
-## Verification
-
-### Check Issue Creation
-
-```bash
-# List issues
-gh issue list --repo your-org/your-repo
-
-# View specific issue
-gh issue view <issue-number> --repo your-org/your-repo
-```
-
-### Check Progress Comments
-
-```bash
-# View latest comment
-gh issue view <issue-number> --repo your-org/your-repo --json comments --jq '.comments[-1].body'
-
-# View all comments
-gh issue view <issue-number> --repo your-org/your-repo --json comments
-```
-
-### Check Source Tracking
-
-Verify `openspec/changes/<change-id>/proposal.md` was updated:
-
-```markdown
-## Source Tracking
-
-- **GitHub Issue**: #123
-- **Issue URL**: <https://github.com/owner/repo/issues/123>
-- **Last Synced Status**: proposed
-- **Sanitized**: false
-<!-- last_code_change_detected: 2025-12-30T10:00:00Z -->
-```
-
----
-
-## Troubleshooting
-
-### "0 backlog items exported" Error
-
-**Problem**: Export command shows "✓ Exported 0 backlog item(s) from bundle" even though change proposals exist.
-
-**Common Causes**:
-
-1. **Using `--bundle` for direct OpenSpec export** (most common):
-
- ```bash
- # ❌ WRONG: Using --bundle when exporting from OpenSpec
- specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name your-repo \
- --bundle some-bundle \
- --change-ids add-feature-x \
- --repo /path/to/openspec-repo
- ```
-
-2. **Bundle doesn't contain the proposal**:
- - Proposal was never imported into the bundle
- - Bundle name is incorrect
- - Proposal was created in OpenSpec but not imported to bundle
-
-**Solutions**:
-
-- **For direct OpenSpec export** (most common): Remove `--bundle` flag:
-
- ```bash
- # ✅ CORRECT: Direct export from OpenSpec
- specfact project sync bridge --adapter github --mode export-only \
- --repo-owner your-org --repo-name your-repo \
- --change-ids add-feature-x \
- --repo /path/to/openspec-repo
- ```
-
-- **For bundle export** (cross-adapter sync): Import proposal into bundle first:
-
- ```bash
- # Step 1: Import from backlog into bundle
- specfact project sync bridge --adapter github --mode bidirectional \
- --repo-owner your-org --repo-name your-repo \
- --bundle your-bundle \
- --backlog-ids 123
-
- # Step 2: Export from bundle (now it will work)
- specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org --ado-project your-project \
- --bundle your-bundle \
- --change-ids <change-id-from-step-1>
- ```
-
-- **Verify proposal exists**:
-
- ```bash
- # Check OpenSpec directory
- ls openspec/changes/<change-id>/
-
- # Check bundle directory (if using --bundle)
- ls .specfact/projects/<bundle-name>/change_tracking/proposals/
- ```
-
-**See also**: [When to Use `--bundle` vs Direct Export](#when-to-use---bundle-vs-direct-export) section above.
-
-### No Commits Detected
-
-**Problem**: Code changes not detected even though commits exist.
-
-**Solutions**:
-
-- Ensure commit messages include the change proposal ID (e.g., "add-feature-x")
-- Verify `--code-repo` points to the correct source code repository
-- Check that `last_code_change_detected` timestamp isn't in the future (reset if needed)
-
-### Wrong Repository
-
-**Problem**: Commits detected from wrong repository.
-
-**Solutions**:
-
-- Verify `--code-repo` parameter points to source code repository
-- Check that OpenSpec repository (`--repo`) is correct
-- Ensure both repositories are valid Git repositories
-
-### No Comments Added
-
-**Problem**: Progress comments not added to issues.
-
-**Solutions**:
-
-- Verify issues exist (create them first without `--track-code-changes`)
-- Check GitHub token has write permissions
-- Verify change proposal ID matches commit messages
-- Check for duplicate comments (may be skipped)
-
-### Sanitization Issues
-
-**Problem**: Too much or too little content sanitized.
-
-**Solutions**:
-
-- Use `--sanitize` for public repos, `--no-sanitize` for internal repos
-- Check auto-detection logic (different repos → sanitize, same repo → no sanitization)
-- Review proposal content to ensure sensitive information is properly marked
-
-### Authentication Errors
-
-**Problem**: GitHub authentication fails.
-
-**Solutions**:
-
-- Verify GitHub token is valid: `gh auth status`
-- Check token permissions (read/write access)
-- Try using `--use-gh-cli` flag
-- Verify `GITHUB_TOKEN` environment variable is set correctly
-
----
-
-## Best Practices
-
-### Commit Messages
-
-- Always include change proposal ID in commit messages
-- Use descriptive commit messages that explain what was changed
-- Follow conventional commit format: `type: change-id - description`
-
-### Repository Organization
-
-- Keep OpenSpec proposals in a dedicated repository for better organization
-- Use `--code-repo` when OpenSpec and source code are separate
-- Document repository structure in your team's documentation
-
-### Content Sanitization
-
-- Always sanitize when exporting to public repositories
-- Review sanitized content before syncing to ensure nothing sensitive leaks
-- Use `--no-sanitize` only for internal repositories
-
-### Progress Tracking
-
-- Run `--track-code-changes` regularly (e.g., after each commit or daily)
-- Use manual progress comments for non-code updates (meetings, decisions, etc.)
-- Verify comments are added correctly after each sync
-
-### Issue Management
-
-- Create issues first, then track code changes
-- Use `--update-existing` sparingly (only when proposal content changes significantly)
-- Monitor issue comments to ensure progress tracking is working
-
----
-
-## See Also
-
-### Related Guides
-
-- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations
-
-- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain)
-- Common Tasks Index - Quick reference for DevOps integration tasks
-- [OpenSpec Journey](openspec-journey.md) - OpenSpec integration with DevOps export
-- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Persona-based backlog management
-
-### Related Commands
-
-- [Command Reference - Sync Bridge](../reference/commands.md#sync-bridge) - Complete `sync bridge` command documentation
-- [Command Reference - DevOps Adapters](../reference/commands.md#sync-bridge) - Adapter configuration
-
-### Related Examples
-
-- [DevOps Integration Examples](../examples/) - Real-world integration examples
-
-### Architecture & Troubleshooting
-
-- [Architecture](../architecture/overview.md) - System architecture and design
-- [Troubleshooting](troubleshooting.md) - Common issues and solutions
-
----
-
-## Azure DevOps Integration
-
-Azure DevOps adapter (`--adapter ado`) is now available and supports:
-
-- **Bidirectional Sync**: Import ADO work items as OpenSpec change proposals AND export proposals as work items
-- **Work Item Creation**: Export OpenSpec change proposals as ADO work items
-- **Work Item Import**: Import ADO work items as OpenSpec change proposals
-- **Status Synchronization**: Bidirectional status sync (OpenSpec ↔ ADO state) with conflict resolution
-- **Status Comments**: Automatic status change comments (applied, deprecated, discarded, in-progress)
-- **Progress Tracking**: Code change detection and progress comments (same as GitHub)
-- **Work Item Type Derivation**: Automatically detects work item type from process template (Scrum/Kanban/Agile)
-- **Work Item Updates**: Update existing work items with `--update-existing` flag
-- **Markdown Format Support**: Proper markdown rendering in work item descriptions
-
-### Prerequisites
-
-- Azure DevOps organization and project
-- Personal Access Token (PAT) with work item read/write permissions **or** device code auth via `specfact backlog auth azure-devops`
-- OpenSpec change proposals in `openspec/changes/<change-id>/proposal.md`
-
-### Authentication
-
-```bash
-# Option 1: Device Code (SSO-friendly)
-specfact backlog auth azure-devops
-
-# Option 2: Environment Variable
-export AZURE_DEVOPS_TOKEN=your_pat_token
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org \
- --ado-project your-project \
- --repo /path/to/openspec-repo
-
-# Option 3: Command Line Flag
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org \
- --ado-project your-project \
- --ado-token your_pat_token \
- --repo /path/to/openspec-repo
-```
-
-### Basic Usage
-
-```bash
-# Bidirectional sync (import work items AND export proposals)
-specfact project sync bridge --adapter ado --bidirectional \
- --ado-org your-org \
- --ado-project your-project \
- --repo /path/to/openspec-repo
-
-# Export-only (one-way: OpenSpec → ADO)
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org \
- --ado-project your-project \
- --repo /path/to/openspec-repo
-
-# Export with explicit work item type
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org \
- --ado-project your-project \
- --ado-work-item-type "User Story" \
- --repo /path/to/openspec-repo
-
-# Track code changes and add progress comments
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org \
- --ado-project your-project \
- --track-code-changes \
- --repo /path/to/openspec-repo \
- --code-repo /path/to/source-code-repo
-```
-
-### Work Item Type Derivation
-
-The ADO adapter automatically derives work item type from your project's process template:
-
-- **Scrum**: `Product Backlog Item`
-- **Agile**: `User Story`
-- **Kanban**: `User Story` (default)
-
-You can override with `--ado-work-item-type`:
-
-```bash
-specfact project sync bridge --adapter ado --mode export-only \
- --ado-org your-org \
- --ado-project your-project \
- --ado-work-item-type "Bug" \
- --repo /path/to/openspec-repo
-```
-
-### Status Mapping
-
-ADO states map to OpenSpec status as follows:
-
-| ADO State | OpenSpec Status |
-|-----------|----------------|
-| `New` | `proposed` |
-| `Active` / `In Progress` | `in-progress` |
-| `Closed` / `Done` | `applied` |
-| `Removed` | `deprecated` |
-| `Rejected` | `discarded` |
-
-### Configuration
-
-All ADO-specific configuration can be provided via:
-
-- **CLI flags**: `--ado-org`, `--ado-project`, `--ado-base-url`, `--ado-token`, `--ado-work-item-type`
-- **Environment variables**: `AZURE_DEVOPS_TOKEN`, `ADO_BASE_URL` (defaults to `https://dev.azure.com`)
-
-## Future Adapters
-
-Additional DevOps adapters are planned:
-
-- **Linear** (`--adapter linear`) - Issues and progress updates
-- **Jira** (`--adapter jira`) - Issues, epics, and sprint tracking
-
-These will follow similar patterns to GitHub Issues and Azure DevOps integration. Check the [Commands Reference](../reference/commands.md) for the latest adapter support.
-
----
-
-**Need Help?**
-
-- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
-- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
-- 📧 [hello@noldai.com](mailto:hello@noldai.com)
+**Full guide on the canonical modules docs site:** [DevOps adapter overview](https://modules.specfact.io/integrations/devops-adapter-overview/)
diff --git a/docs/guides/import-features.md b/docs/guides/import-features.md
index 47713f2c..5bdb2dc0 100644
--- a/docs/guides/import-features.md
+++ b/docs/guides/import-features.md
@@ -2,250 +2,13 @@
layout: default
title: Import Command Features
permalink: /guides/import-features/
+description: Handoff to import and migration features on the modules documentation site.
---
-# Import Command Features
+# Import command features
+Import flows bring external plans, code, and bridge data into SpecFact-managed bundles. Feature matrices, flags, and migration notes are documented with the project bundle on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Directory structure](https://docs.specfact.io/reference/directory-structure/) for bundle layout; `code import` and related commands in [Commands](https://docs.specfact.io/reference/commands/).
-This guide covers advanced features and optimizations in the `import from-code` command.
-
-## Overview
-
-The `import from-code` command has been optimized for large codebases and includes several features to improve reliability, performance, and user experience:
-
-- **Progress Reporting**: Real-time progress bars for long-running operations
-- **Feature Validation**: Automatic validation of existing features when resuming imports
-- **Early Save Checkpoint**: Features saved immediately after analysis to prevent data loss
-- **Performance Optimizations**: Pre-computed caches for 5-15x faster processing
-- **Re-validation Flag**: Force re-analysis of features even if files haven't changed
-
----
-
-## Progress Reporting
-
-The import command now provides detailed progress reporting for all major operations:
-
-### Feature Analysis Progress
-
-During the initial codebase analysis, you'll see:
-
-```
-🔍 Analyzing codebase...
-✓ Found 3156 features
-✓ Detected themes: API, Async, Database, ORM, Testing
-✓ Total stories: 5604
-```
-
-### Source File Linking Progress
-
-When linking source files to features, a progress bar shows:
-
-```
-Linking 3156 features to source files...
-[████████████████████] 100% (3156/3156 features)
-```
-
-This is especially useful for large codebases where linking can take several minutes.
-
-### Contract Extraction Progress
-
-During OpenAPI contract extraction, progress is shown for each feature being processed.
-
----
-
-## Feature Validation
-
-When you restart an import on an existing bundle, the command automatically validates existing features:
-
-### Automatic Validation
-
-```bash
-# First import
-specfact code import my-project --repo .
-
-# Later, restart import (validates existing features automatically)
-specfact code import my-project --repo .
-```
-
-### Validation Results
-
-The command reports validation results:
-
-```
-🔍 Validating existing features...
-✓ All 3156 features validated successfully (source files exist)
-```
-
-Or if issues are found:
-
-```
-⚠ Feature validation found issues: 3100/3156 valid, 45 orphaned, 11 invalid
- Orphaned features (all source files missing):
- - FEATURE-1234 (3 missing files)
- - FEATURE-5678 (2 missing files)
- ...
- Invalid features (some files missing or structure issues):
- - FEATURE-9012 (1 missing file)
- ...
- Tip: Use --revalidate-features to re-analyze features and fix issues
-```
-
-### What Gets Validated
-
-- **Source file existence**: Checks that all referenced implementation and test files still exist
-- **Feature structure**: Validates that features have required fields (key, title, stories)
-- **Orphaned features**: Detects features whose source files have been deleted
-- **Invalid features**: Identifies features with missing files or structural issues
-
----
-
-## Early Save Checkpoint
-
-Features are saved immediately after the initial codebase analysis, before expensive operations like source tracking and contract extraction.
-
-### Benefits
-
-- **Resume capability**: If the import is interrupted, you can restart without losing the initial analysis
-- **Data safety**: Features are persisted early, reducing risk of data loss
-- **Faster recovery**: No need to re-run the full codebase scan if interrupted
-
-### Example
-
-```bash
-# Start import
-specfact code import my-project --repo .
-
-# Output shows:
-# ✓ Found 3156 features
-# 💾 Saving features (checkpoint)...
-# ✓ Features saved (can resume if interrupted)
-
-# If you press Ctrl+C during source linking, you can restart:
-specfact code import my-project --repo .
-# The command will detect existing features and resume from checkpoint
-```
-
----
-
-## Performance Optimizations
-
-The import command has been optimized for large codebases (3000+ features):
-
-### Pre-computed Caches
-
-- **AST Parsing**: All files are parsed once before parallel processing
-- **File Hashes**: All file hashes are computed once and cached
-- **Function Mappings**: Function names are extracted once per file
-
-### Performance Improvements
-
-- **Before**: ~34 features/minute (515/3156 in 15 minutes)
-- **After**: 200-500+ features/minute (5-15x faster)
-- **Large codebases**: 3000+ features processed in 6-15 minutes (down from 90+ minutes)
-
-### How It Works
-
-1. **Pre-computation phase**: Single pass through all files to build caches
-2. **Parallel processing**: Uses cached results (no file I/O or AST parsing)
-3. **Thread-safe**: Read-only caches during parallel execution
-
----
-
-## Re-validation Flag
-
-Use `--revalidate-features` to force re-analysis even if source files haven't changed.
-
-### When to Use
-
-- **Analysis improvements**: When the analysis logic has been improved
-- **Confidence changes**: When you want to re-evaluate features with a different confidence threshold
-- **File changes outside repo**: When files were moved or renamed outside the repository
-- **Validation issues**: When validation reports orphaned or invalid features
-
-### Example
-
-```bash
-# Re-analyze all features even if files unchanged
-specfact code import my-project --repo . --revalidate-features
-
-# Output shows:
-# ⚠ --revalidate-features enabled: Will re-analyze features even if files unchanged
-```
-
-### What Happens
-
-- Forces full codebase analysis regardless of incremental change detection
-- Re-computes all feature mappings and source tracking
-- Updates feature confidence scores based on current analysis logic
-- Regenerates all contracts and relationships
-
----
-
-## Best Practices
-
-### Large Codebases
-
-For codebases with 1000+ features:
-
-1. **Use partial analysis**: Start with `--entry-point` to analyze one module at a time
-2. **Monitor progress**: Watch the progress bars to estimate completion time
-3. **Use checkpoints**: Let the early save checkpoint work for you - don't worry about interruptions
-4. **Re-validate periodically**: Use `--revalidate-features` after major code changes
-
-### Resuming Interrupted Imports
-
-1. **Don't delete the bundle**: The checkpoint is stored in the bundle directory
-2. **Run the same command**: Just re-run the import command - it will detect existing features
-3. **Check validation**: Review validation results to see if any features need attention
-4. **Use re-validation if needed**: If validation shows issues, use `--revalidate-features`
-
-### Performance Tips
-
-1. **Exclude tests if not needed**: Use `--exclude-tests` for faster processing (if test analysis isn't critical)
-2. **Use entry points**: For monorepos, analyze one project at a time with `--entry-point`
-3. **Adjust confidence**: Lower confidence (0.3-0.5) for faster analysis, higher (0.7-0.9) for more accurate results
-
----
-
-## Troubleshooting
-
-### Slow Linking
-
-If source file linking is slow:
-
-- **Check file count**: Large numbers of files (10,000+) will take longer
-- **Monitor progress**: The progress bar shows current status
-- **Use entry points**: Limit scope with `--entry-point` for faster processing
-
-### Validation Issues
-
-If validation reports many orphaned features:
-
-- **Check file paths**: Ensure source files haven't been moved
-- **Use re-validation**: Run with `--revalidate-features` to fix mappings
-- **Review feature keys**: Some features may need manual adjustment
-
-### Interrupted Imports
-
-If import is interrupted:
-
-- **Don't delete bundle**: The checkpoint is in `.specfact/projects/<bundle-name>/`
-- **Restart command**: Run the same import command - it will resume
-- **Check progress**: Validation will show what was completed
-
----
-
-## Related Documentation
-
-- [Command Reference](../reference/commands.md#import-from-code) - Complete command documentation
-- [Quick Examples](../examples/quick-examples.md) - Quick command examples
-- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete brownfield workflow
-- Common Tasks - Common import scenarios
-
----
-
-**Happy importing!** 🚀
+**Full guide on the canonical modules docs site:** [Import migration](https://modules.specfact.io/bundles/project/import-migration/)
diff --git a/docs/guides/policy-engine-commands.md b/docs/guides/policy-engine-commands.md
index 968ffb43..162e2df1 100644
--- a/docs/guides/policy-engine-commands.md
+++ b/docs/guides/policy-engine-commands.md
@@ -2,143 +2,13 @@
layout: default
title: Policy Engine Commands
permalink: /guides/policy-engine-commands/
+description: Handoff to policy engine commands on the modules documentation site.
---
-# Policy Engine Commands
+# Policy engine commands
+The policy engine applies org rules to backlog and code workflows—gates, checks, and enforcement surfaces. Command lists, configuration, and examples are maintained with the policy bundle for backlog workflows on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Govern](https://docs.specfact.io/reference/commands/)-related commands in the reference; backlog modules installed as needed.
-> **Note**: `backlog policy` commands were removed. The equivalent workflows are now under `backlog verify-readiness`, `backlog refine`, and `backlog ceremony`.
-
-Use SpecFact policy commands to validate readiness, refine backlog items, and run agile ceremonies.
-
-## Overview
-
-The policy engine currently supports:
-
-- `specfact backlog verify-readiness` to evaluate configured rules deterministically against policy input artifacts.
-- `specfact backlog refine` to generate confidence-scored, patch-ready recommendations (no automatic writes).
-- `specfact backlog ceremony` to run agile ceremonies (standup, refinement, etc.).
-
-## Commands
-
-### Verify Readiness
-
-Check that backlog items meet Definition of Ready / Definition of Done criteria:
-
-```bash
-specfact backlog verify-readiness --repo . --format both
-```
-
-Artifact resolution order when `--snapshot` is omitted:
-
-1. `.specfact/backlog-baseline.json`
-2. Latest `.specfact/plans/backlog-*.yaml|yml|json`
-
-You can still override with an explicit path:
-
-```bash
-specfact backlog verify-readiness --repo . --snapshot ./snapshot.json --format both
-```
-
-Filter and scope output:
-
-```bash
-# only one rule family, max 20 findings
-specfact backlog verify-readiness --repo . --rule scrum.dor --limit 20 --format json
-
-# item-centric grouped output
-specfact backlog verify-readiness --repo . --group-by-item --format both
-
-# in grouped mode, --limit applies to item groups
-specfact backlog verify-readiness --repo . --group-by-item --limit 4 --format json
-```
-
-Output formats:
-
-- `json`
-- `markdown`
-- `both`
-
-When config is missing or invalid, the command prints a docs hint pointing back to this policy format guidance.
-
-### Refine Backlog Items
-
-Generate suggestions from readiness findings:
-
-```bash
-specfact backlog refine --repo .
-```
-
-Suggestion shaping options:
-
-```bash
-# suggestions for one rule family, limited output
-specfact backlog refine --repo . --rule scrum.dod --limit 10
-
-# grouped suggestions by backlog item index
-specfact backlog refine --repo . --group-by-item
-
-# grouped mode limits item groups, not per-item fields
-specfact backlog refine --repo . --group-by-item --limit 4
-```
-
-Suggestions include confidence scores and patch-ready structure, but no file is modified automatically.
-
-### Run Agile Ceremonies
-
-Run standup or refinement ceremonies:
-
-```bash
-specfact backlog ceremony standup
-specfact backlog ceremony refinement
-```
-
-## Policy File Location and Format
-
-Expected location:
-
-- `.specfact/policy.yaml`
-
-Minimal structure:
-
-```yaml
-scrum:
- dor_required_fields: [acceptance_criteria]
- dod_required_fields: [definition_of_done]
-kanban:
- columns:
- In Progress:
- exit_required_fields: [qa_status]
-safe:
- pi_readiness_required_fields: [risk_owner]
-```
-
-## Template Assets
-
-Built-in templates are shipped from:
-
-- `resources/templates/policies/`
-
-These templates are intended as a starting point and should be adjusted to team/project policy needs.
-
-## Accepted Policy Input Shapes
-
-Policy commands normalize these payload structures:
-
-- `[{...}, {...}]`
-- `{ items: [{...}, {...}] }`
-- `{ items: { "ID-1": {...}, "ID-2": {...} } }`
-- `{ backlog_graph: { items: [...] } }`
-- `{ backlog_graph: { items: { "ID-1": {...} } } }`
-
-## Compatibility Mapping for Imported Artifacts
-
-Before evaluating rules, policy input normalization maps common aliases to canonical policy fields:
-
-- `acceptance_criteria` from aliases such as `acceptanceCriteria`, `System.AcceptanceCriteria`, or description section `## Acceptance Criteria`
-- `business_value` from aliases such as `businessValue` or `Microsoft.VSTS.Common.BusinessValue`
-- `definition_of_done` from aliases such as `definitionOfDone` or description section `## Definition of Done`
+**Full guide on the canonical modules docs site:** [Policy engine](https://modules.specfact.io/bundles/backlog/policy-engine/)
diff --git a/docs/guides/project-devops-flow.md b/docs/guides/project-devops-flow.md
index ac793402..91412f4f 100644
--- a/docs/guides/project-devops-flow.md
+++ b/docs/guides/project-devops-flow.md
@@ -2,54 +2,13 @@
layout: default
title: Project DevOps Flow
permalink: /guides/project-devops-flow/
+description: Handoff to project DevOps flow stages on the modules documentation site.
---
-# Project DevOps Flow
+# Project DevOps flow
+The project DevOps flow ties plan, develop, review, release, and monitor stages to SpecFact commands and checkpoints. Stage-by-stage guidance and examples are owned by the project bundle documentation.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Architecture overview](https://docs.specfact.io/architecture/overview/) for how modules register commands.
-Use `specfact project devops-flow` to run an integrated lifecycle against a linked backlog provider.
-
-## Prerequisite
-
-Link the bundle once:
-
-```bash
-specfact project link-backlog --bundle <bundle> --adapter <github|ado> --project-id <provider-project-id>
-```
-
-## Stage Actions
-
-```bash
-specfact project devops-flow --bundle <bundle> --stage plan --action generate-roadmap
-specfact project devops-flow --bundle <bundle> --stage develop --action sync
-specfact project devops-flow --bundle <bundle> --stage review --action validate-pr
-specfact project devops-flow --bundle <bundle> --stage release --action verify
-specfact project devops-flow --bundle <bundle> --stage monitor --action health-check
-```
-
-Supported pairs are fixed and validated by CLI:
-
-- `plan/generate-roadmap`
-- `develop/sync`
-- `review/validate-pr`
-- `release/verify`
-- `monitor/health-check`
-
-## Related Project Commands
-
-```bash
-specfact project health-check --bundle <bundle>
-specfact project snapshot --bundle <bundle>
-specfact project regenerate --bundle <bundle> [--strict] [--verbose]
-specfact project export-roadmap --bundle <bundle>
-```
-
-`project regenerate` behavior:
-
-- default: summary-only mismatch output, non-failing
-- `--verbose`: prints detailed mismatch lines
-- `--strict`: exits non-zero when mismatches are detected
+**Full guide on the canonical modules docs site:** [Project DevOps flow](https://modules.specfact.io/bundles/project/devops-flow/)
diff --git a/docs/guides/sidecar-validation.md b/docs/guides/sidecar-validation.md
index cc8cebff..0e5c1e73 100644
--- a/docs/guides/sidecar-validation.md
+++ b/docs/guides/sidecar-validation.md
@@ -2,573 +2,13 @@
layout: default
title: Sidecar Validation Guide
permalink: /guides/sidecar-validation/
+description: Handoff to sidecar validation on the modules documentation site.
---
-# Sidecar Validation Guide
+# Sidecar validation
+Sidecar validation runs checks alongside your codebase—contracts, templates, and integration points—without replacing your main app. Setup, CLI flags, and CI patterns are documented under the codebase bundle on modules.
-> Modules docs handoff: this page remains in the core docs set as release-line overview content.
-> Canonical bundle-specific deep guidance now lives in the canonical modules docs site, currently
-> published at `https://modules.specfact.io/`.
+**Prerequisites:** [Thorough codebase validation](https://docs.specfact.io/reference/thorough-codebase-validation/) entry point on core; Python 3.11+ per project standards.
-Complete guide for using sidecar validation to validate external codebases without modifying source code.
-
-## Overview
-
-Sidecar validation enables contract-based validation of external codebases (libraries, APIs, frameworks) without requiring modifications to the source code. This is particularly useful for:
-
-- **Validating third-party libraries** without forking or modifying them
-- **Testing legacy codebases** where direct modifications are risky
-- **Contract validation** of APIs where you don't control the implementation
-- **Framework validation** (Django, FastAPI, DRF, Flask) using extracted routes and schemas
-
-## Quick Start
-
-### 1. Initialize Sidecar Workspace
-
-```bash
-specfact code validate sidecar init <bundle-name> <repo-path>
-```
-
-**Example:**
-
-```bash
-specfact code validate sidecar init legacy-api /path/to/django-project
-```
-
-This will:
-
-- Detect the framework type (Django, FastAPI, DRF, pure-python)
-- Create sidecar workspace directory structure
-- Generate configuration files
-- Detect Python environment (venv, poetry, uv, pip)
-- Set up framework-specific configuration
-
-### 2. Run Validation
-
-```bash
-specfact code validate sidecar run <bundle-name> <repo-path>
-```
-
-**Example:**
-
-```bash
-# Run full validation (CrossHair + Specmatic)
-specfact code validate sidecar run legacy-api /path/to/django-project
-
-# Run only CrossHair analysis
-specfact code validate sidecar run legacy-api /path/to/django-project --no-run-specmatic
-
-# Run only Specmatic validation
-specfact code validate sidecar run legacy-api /path/to/django-project --no-run-crosshair
-```
-
-## Workflow
-
-### Step 1: Framework Detection
-
-The sidecar validation automatically detects the framework type:
-
-- **Django**: Detects `manage.py` or `urls.py` files
-- **FastAPI**: Detects `FastAPI()` or `@app.get()` patterns
-- **DRF**: Detects `rest_framework` imports (if Django is also present)
-- **Flask**: Detects `Flask()` instantiation or `from flask import Flask` imports
-- **Pure Python**: No framework detected
-
-### Step 2: Route Extraction
-
-Framework-specific extractors extract routes and schemas:
-
-- **Django**: Extracts URL patterns from `urls.py` and form schemas
-- **FastAPI**: Extracts routes from decorators and Pydantic models
-- **DRF**: Extracts serializers and converts to OpenAPI schemas
-- **Flask**: Extracts routes from `@app.route()` and `@bp.route()` decorators, converts path parameters (`<int:id>`, `<slug>`, etc.) to OpenAPI format
-
-### Step 3: Contract Population
-
-OpenAPI contracts are populated with extracted routes and schemas:
-
-- Routes are matched to contract features
-- Request/response schemas are merged
-- Path parameters are extracted and documented
-- **Expected status codes** are automatically extracted from OpenAPI `responses` sections
-- **Response structure validation** is added based on OpenAPI schemas (required fields, property types, array items)
-
-### Step 4: Harness Generation
-
-CrossHair harness files are generated from populated contracts:
-
-- Creates Python harness with `@icontract` decorators
-- Generates test inputs JSON file
-- Creates bindings YAML for framework adapters
-
-### Step 5: Validation Execution
-
-Validation tools are executed:
-
-- **CrossHair**: Symbolic execution on source code and harness
-- **Specmatic**: Contract testing against API endpoints (if available)
-
-## Supported Frameworks
-
-### Django
-
-**Detection:**
-
-- Looks for `manage.py` or `urls.py` files
-- Auto-detects `DJANGO_SETTINGS_MODULE` from `manage.py`
-
-**Extraction:**
-
-- URL patterns from `urlpatterns` in `urls.py`
-- Form schemas from Django form classes
-- View references (function-based and class-based)
-
-**Example:**
-
-```bash
-specfact code validate sidecar init django-app /path/to/django-project
-specfact code validate sidecar run django-app /path/to/django-project
-```
-
-### FastAPI
-
-**Detection:**
-
-- Looks for `FastAPI()` or `@app.get()` patterns in `main.py` or `app.py`
-
-**Extraction:**
-
-- Route decorators (`@app.get()`, `@app.post()`, etc.)
-- Pydantic models from route signatures
-- Path parameters and request/response schemas
-
-**Example:**
-
-```bash
-specfact code validate sidecar init fastapi-app /path/to/fastapi-project
-specfact code validate sidecar run fastapi-app /path/to/fastapi-project
-```
-
-### Django REST Framework (DRF)
-
-**Detection:**
-
-- Detects Django + `rest_framework` imports
-
-**Extraction:**
-
-- Serializers from DRF serializer classes
-- OpenAPI schema conversion
-- Route patterns from Django URLs
-
-**Example:**
-
-```bash
-specfact code validate sidecar init drf-api /path/to/drf-project
-specfact code validate sidecar run drf-api /path/to/drf-project
-```
-
-### Flask
-
-**Detection:**
-
-- Looks for `Flask()` instantiation or `from flask import Flask` imports
-- Detects Flask route decorators (`@app.route()`, `@bp.route()`)
-
-**Extraction:**
-
-- Route decorators (`@app.route()`, `@bp.route()`)
-- **All HTTP methods** are captured (e.g., `methods=['GET','POST']` generates separate routes for each method)
-- Path parameters converted to OpenAPI format (`<int:id>` → `{id}` with `type: integer`)
-- **Parameter names preserved** for converter-based paths (e.g., `<uuid:user_id>` → `{user_id}`, not `{uuid}`)
-- HTTP methods from decorators
-- Blueprint routes
-
-**Example:**
-
-```bash
-specfact code validate sidecar init flask-app /path/to/flask-project
-specfact code validate sidecar run flask-app /path/to/flask-project
-```
-
-**Dependency Installation:**
-
-Flask applications automatically have dependencies installed in an isolated venv (`.specfact/venv/`) to ensure Flask is available for harness execution:
-
-- Framework dependencies: `flask`, `werkzeug`
-- Validation tools: `crosshair-tool`
-- Harness dependencies: `beartype`, `icontract`
-- Project dependencies: Automatically detected and installed from `requirements.txt`, `pyproject.toml`, etc.
-
-**Route Extraction Details:**
-
-- **Multiple HTTP methods**: Routes with `methods=['GET','POST']` generate separate RouteInfo objects for each method
-- **Converter-based paths**: Routes like `<uuid:user_id>` correctly extract `{user_id}` as the parameter name
-- **Custom converters**: Unknown converters (e.g., `uuid`, custom converters) default to `string` type while preserving parameter names
-
-### Pure Python
-
-**Detection:**
-
-- No framework detected
-
-**Extraction:**
-
-- Basic function extraction (if runtime contracts present)
-- Limited schema extraction
-
-**Example:**
-
-```bash
-specfact code validate sidecar init python-lib /path/to/python-library
-specfact code validate sidecar run python-lib /path/to/python-library
-```
-
-## Configuration
-
-### Sidecar Workspace Structure
-
-After initialization, the sidecar project structure is created at:
-
-```
-.specfact/projects/<bundle-name>/
-├── contracts/ # OpenAPI contract files
-├── harness/ # Generated CrossHair harness files
-│ └── harness_contracts.py
-├── reports/
-│ └── sidecar/ # Validation reports
-```
-
-### Environment Variables
-
-Sidecar validation respects the following environment variables:
-
-- `DJANGO_SETTINGS_MODULE`: Django settings module (auto-detected if not set)
-- `PYTHONPATH`: Python path for module resolution
-- `TEST_MODE`: Set to `true` to disable progress bars (for testing)
-
-## Validation Tools
-
-### CrossHair
-
-**Purpose**: Symbolic execution to verify contracts
-
-**Execution:**
-
-- Runs on source code (if runtime contracts present)
-- Runs on generated harness (external contracts)
-- **Uses venv Python** (`.specfact/venv/bin/python`) when available to ensure framework dependencies are accessible
-- Captures confirmed/not-confirmed/violations
-
-**Configuration:**
-
-- **Overall timeout**: 120 seconds (default) - allows analysis of multiple routes
-- **Per-path timeout**: 10 seconds (default) - prevents single route from blocking others
-- **Per-condition timeout**: 5 seconds (default) - prevents individual checks from hanging
-- Verbose output options
-- Module resolution handling
-
-**Timeout Behavior:**
-
-For complex applications, timeouts are expected and indicate normal operation:
-
-- **"Not confirmed"** status means analysis is working but couldn't complete within timeout
-- **Partial results** are available in summary files even if overall timeout is reached
-- Per-path timeouts ensure progress even if some routes are slow
-
-### Specmatic
-
-**Purpose**: Contract testing against API endpoints
-
-**Execution:**
-
-- Validates API responses against OpenAPI contracts
-- Requires running application server (if `SIDECAR_APP_CMD` configured)
-- Can use Specmatic stub server for testing
-
-**Auto-Skip Behavior:**
-
-Specmatic is automatically skipped when no service configuration is detected. This prevents unnecessary validation attempts when:
-
-- No `test_base_url` is configured
-- No `host` and `port` combination is available
-- No application server command and port are configured
-
-**When Specmatic is Auto-Skipped:**
-
-```bash
-⚠ Skipping Specmatic: No service configuration detected (use --run-specmatic to override)
-```
-
-**Manual Override:**
-
-You can force Specmatic to run even without service configuration using the `--run-specmatic` flag:
-
-```bash
-# Force Specmatic to run (may fail if no service available)
-specfact code validate sidecar run legacy-api /path/to/repo --run-specmatic
-```
-
-**Configuration:**
-
-- Base URL for API (`test_base_url`)
-- Host and port (`host`, `port`)
-- Application server command and port (`cmd`, `port` in app config)
-- Timeout settings
-- Auto-stub server options
-
-## Progress Reporting
-
-Sidecar validation uses Rich console for progress reporting:
-
-- **Interactive terminals**: Full progress bars with animations
-- **CI/CD environments**: Plain text updates (no animations)
-- **Test mode**: Minimal output (progress bars disabled)
-
-Progress phases:
-
-1. Framework detection
-2. Dependency installation (isolated venv creation and package installation)
-3. Route extraction
-4. Contract population (with expected status codes and response structure validation)
-5. Harness generation
-6. CrossHair analysis (using venv Python)
-7. Specmatic validation
-
-## Output and Reports
-
-### Console Output
-
-Validation results are displayed in the console:
-
-```
-Validation Results:
- Framework: django
- Routes extracted: 15
- Contracts populated: 3
- Harness generated: True
-
-CrossHair Results:
- ✓ harness
- CrossHair: 5 confirmed, 2 not confirmed, 1 violations
- Summary file: .specfact/projects/legacy-api/reports/sidecar/crosshair-summary-20240109T120000Z.json
-
-Specmatic Results:
- ✓ FEATURE-001.openapi.yaml
-```
-
-**Note**: If Specmatic is auto-skipped, you'll see:
-
-```
-⚠ Specmatic skipped: No service configuration detected
-```
-
-Instead of the Specmatic Results section.
-
-### Report Files
-
-Reports are saved to `.specfact/projects/<bundle>/reports/sidecar/`:
-
-- CrossHair output and analysis results
-- Specmatic test results and HTML reports
-- Timestamped execution logs
-
-## Troubleshooting
-
-### Framework Not Detected
-
-**Issue**: Framework type shows as `unknown` or `pure-python`
-
-**Solutions:**
-
-- Ensure framework files are present (`manage.py` for Django, `main.py` for FastAPI, `app.py` for Flask)
-- Check that framework imports are present in source files
-- For Flask: Ensure `from flask import Flask` or `import flask` with `Flask()` instantiation
-- Verify repository path is correct
-
-### CrossHair Not Found
-
-**Issue**: Error message "CrossHair not found in PATH"
-
-**Solutions:**
-
-- Install CrossHair: `pip install crosshair-tool`
-- Ensure CrossHair is in PATH
-- Use virtual environment with CrossHair installed
-
-### Specmatic Not Found
-
-**Issue**: Error message "Specmatic not found in PATH"
-
-**Solutions:**
-
-- Install Specmatic (CLI, JAR, npm, or Python module)
-- Ensure `specmatic` is available on PATH
-- Skip Specmatic if not needed: `--no-run-specmatic`
-
-### Specmatic Auto-Skipped
-
-**Issue**: Specmatic is automatically skipped with message "No service configuration detected"
-
-**Explanation:**
-Specmatic requires a service endpoint to test against. If no service configuration is detected, Specmatic is automatically skipped to avoid unnecessary validation attempts.
-
-**When This Happens:**
-
-- No `test_base_url` configured in SpecmaticConfig
-- No `host` and `port` combination available
-- No application server command and port configured
-
-**Solutions:**
-
-1. **Ensure Specmatic is installed and on PATH**
-2. **Make sure your Specmatic configuration/service is available** (e.g., config file in the repo or a running service)
-3. **Re-run with Specmatic enabled**:
-
- ```bash
- specfact code validate sidecar run legacy-api /path/to/repo --run-specmatic
- ```
-
-4. **Skip Specmatic explicitly** (if you only need CrossHair):
-
- ```bash
- specfact code validate sidecar run legacy-api /path/to/repo --no-run-specmatic
- ```
-
-### Module Resolution Errors
-
-**Issue**: CrossHair fails with import errors
-
-**Solutions:**
-
-- **Automatic**: Sidecar validation automatically sets PYTHONPATH to include venv site-packages
-- **Venv Python**: CrossHair uses venv Python (`.specfact/venv/bin/python`) when available, ensuring framework dependencies are accessible
-- Set `PYTHONPATH` correctly for your project structure (if manual override needed)
-- Ensure source directories are in PYTHONPATH
-- Check that `__init__.py` files are present for packages
-
-### Dependency Installation Issues
-
-**Issue**: Dependencies not installed or venv broken
-
-**Solutions:**
-
-- **Automatic recreation**: The system automatically detects and recreates broken venvs
-- **Check venv**: Verify `.specfact/venv/` exists and contains installed packages
-- **Re-run validation**: Delete `.specfact/venv/` and re-run validation to trigger fresh installation
-- **Manual installation**: If automatic installation fails, manually install dependencies:
-
- ```bash
- cd /path/to/repo
- python3 -m venv .specfact/venv --copies
- .specfact/venv/bin/pip install flask werkzeug crosshair-tool beartype icontract
- .specfact/venv/bin/pip install -r requirements.txt
- ```
-
-## Examples
-
-### Example 1: Django Application
-
-```bash
-# Initialize
-specfact code validate sidecar init django-blog /path/to/django-blog
-
-# Run validation
-specfact code validate sidecar run django-blog /path/to/django-blog
-```
-
-### Example 2: FastAPI API
-
-```bash
-# Initialize
-specfact code validate sidecar init fastapi-api /path/to/fastapi-api
-
-# Run only CrossHair (no HTTP endpoints - Specmatic auto-skipped)
-specfact code validate sidecar run fastapi-api /path/to/fastapi-api --no-run-specmatic
-
-# Or let auto-skip handle it (Specmatic will be skipped automatically)
-specfact code validate sidecar run fastapi-api /path/to/fastapi-api
-```
-
-**Note**: In this example, Specmatic is automatically skipped because no service configuration is provided. The validation will focus on CrossHair analysis only.
-
-### Example 3: Flask Application
-
-```bash
-# Initialize
-specfact code validate sidecar init flask-app /path/to/flask-project
-
-# Run validation (dependencies automatically installed in isolated venv)
-specfact code validate sidecar run flask-app /path/to/flask-project --no-run-specmatic
-```
-
-**Note**: Flask applications automatically have dependencies installed in `.specfact/venv/` during initialization. All HTTP methods are captured (e.g., routes with `methods=['GET','POST']` generate separate routes for each method).
-
-### Example 4: Pure Python Library
-
-```bash
-# Initialize
-specfact code validate sidecar init python-lib /path/to/python-library
-
-# Run validation
-specfact code validate sidecar run python-lib /path/to/python-library
-```
-
-## Repro Integration
-
-Sidecar validation can be integrated into the `specfact code repro` command for validating unannotated code as part of the reproducibility suite.
-
-### Using Sidecar with Repro
-
-```bash
-# Run repro with sidecar validation for unannotated code
-specfact code repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo
-```
-
-**What it does:**
-
-1. Detects unannotated functions (no icontract/beartype decorators) using AST parsing
-2. Generates sidecar harness for unannotated code paths
-3. Runs CrossHair against the generated harness (not source code)
-4. Applies safe defaults (shorter timeouts, per-path limits) to prevent excessive execution time
-5. Uses deterministic inputs when available
-
-**Safe Defaults for Repro Mode:**
-
-When used with `specfact code repro --sidecar`, sidecar validation automatically applies safe defaults:
-
-- **CrossHair timeout**: 30 seconds (vs 60 default)
-- **Per-path timeout**: 5 seconds
-- **Per-condition timeout**: 2 seconds
-- **Deterministic inputs**: Enabled (uses inputs.json from harness)
-
-**Example:**
-
-```bash
-# Initialize sidecar workspace first
-specfact code validate sidecar init legacy-api /path/to/repo
-
-# Then run repro with sidecar validation
-specfact code repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo --verbose
-```
-
-**Output:**
-
-```
-Running sidecar validation for unannotated code...
-Found 12 unannotated functions
-[sidecar validation runs...]
-Sidecar CrossHair: 8 confirmed, 3 not confirmed, 1 violations
-```
-
-## Related Documentation
-
-- **[Command Reference](../reference/commands.md)** - Complete command documentation
-- **[Contract Testing Workflow](contract-testing-workflow.md)** - Contract testing guide
-- **[Specmatic Integration](specmatic-integration.md)** - Specmatic integration details
-
-## See Also
-
-- **[Brownfield Engineer Guide](brownfield-engineer.md)** - Modernizing legacy code
-- **[Use Cases](use-cases.md)** - Real-world scenarios
+**Full guide on the canonical modules docs site:** [Sidecar validation](https://modules.specfact.io/bundles/codebase/sidecar-validation/)
diff --git a/docs/guides/specmatic-integration.md b/docs/guides/specmatic-integration.md
index 9a1cfd7f..bebbe874 100644
--- a/docs/guides/specmatic-integration.md
+++ b/docs/guides/specmatic-integration.md
@@ -2,648 +2,13 @@
layout: default
title: Specmatic Integration
permalink: /guides/specmatic-integration/
+description: Handoff to Specmatic integration on the modules documentation site.
---
-# Specmatic Integration Guide
+# Specmatic integration
-> **API Contract Testing with Specmatic**
-> Validate OpenAPI/AsyncAPI specifications, check backward compatibility, and run mock servers
+Integrate Specmatic with SpecFact for contract-driven API development—mock servers, tests, and pipeline hooks. Setup, CLI mapping, and version notes live on the modules documentation site.
----
-
-## Overview
-
-SpecFact CLI integrates with **Specmatic** to provide service-level contract testing for API specifications. This complements SpecFact's code-level contracts (icontract, beartype, CrossHair) by adding API contract validation.
-
-**What Specmatic adds:**
-
-- ✅ **OpenAPI/AsyncAPI validation** - Validate specification structure and examples
-- ✅ **Backward compatibility checking** - Detect breaking changes between spec versions
-- ✅ **Mock server generation** - Run development mock servers from specifications
-- ✅ **Test suite generation** - Auto-generate contract tests from specs
-
----
-
-## Quick Reference: When to Use What
-
-| Command | Purpose | Output | When to Use |
-|---------|---------|--------|-------------|
-| `spec validate` | **Check if spec is valid** | Validation report (console) | Before committing spec changes, verify spec correctness |
-| `spec generate-tests` | **Create tests to validate API** | Test files (on disk) | To test your API implementation matches the spec |
-| `spec mock` | **Run mock server** | Running server | Test client code, frontend development |
-| `spec backward-compat` | **Check breaking changes** | Compatibility report | When updating API versions |
-
-**Key Difference:**
-
-- `validate` = "Is my spec file correct?" (checks the specification itself)
-- `generate-tests` = "Create tests to verify my API matches the spec" (creates executable tests)
-
-**Typical Workflow:**
-
-```bash
-# 1. Validate spec is correct
-specfact spec validate --bundle my-api
-
-# 2. Generate tests from spec
-specfact spec generate-tests --bundle my-api --output tests/
-
-# 3. Run tests against your API
-specmatic test --spec ... --host http://localhost:8000
-```
-
----
-
-## Installation
-
-**Important**: Specmatic is a **Java CLI tool**, not a Python package. It must be installed separately.
-
-### Install Specmatic
-
-Visit the [Specmatic download page](https://docs.specmatic.io/download.html) for detailed installation instructions.
-
-**Quick install options:**
-
-```bash
-# Option 1: Direct installation (requires Java 17+)
-# macOS/Linux
-curl https://docs.specmatic.io/install-specmatic.sh | bash
-
-# Windows (PowerShell)
-irm https://docs.specmatic.io/install-specmatic.ps1 | iex
-
-# Option 2: Via npm/npx (requires Java/JRE and Node.js)
-# Run directly without installation
-npx specmatic --version
-
-# Option 3: macOS (Homebrew)
-brew install specmatic
-
-# Verify installation
-specmatic --version
-```
-
-**Note**: SpecFact CLI automatically detects Specmatic whether it's installed directly or available via `npx`. If you have Java/JRE installed, you can use `npx specmatic` without a separate installation.
-
-### Verify Integration
-
-SpecFact CLI will automatically detect if Specmatic is available:
-
-```bash
-# Check if Specmatic is detected
-specfact spec validate --help
-
-# If Specmatic is not installed, you'll see:
-# ✗ Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/
-```
-
----
-
-## Commands
-
-### Validate Specification
-
-Validate an OpenAPI/AsyncAPI specification. Can validate a single file or all contracts in a project bundle:
-
-```bash
-# Validate a single spec file
-specfact spec validate api/openapi.yaml
-
-# With backward compatibility check
-specfact spec validate api/openapi.yaml --previous api/openapi.v1.yaml
-
-# Validate all contracts in active bundle (interactive selection)
-specfact spec validate
-
-# Validate all contracts in specific bundle
-specfact spec validate --bundle legacy-api
-
-# Non-interactive: validate all contracts in active bundle
-specfact spec validate --bundle legacy-api --no-interactive
-```
-
-**CLI-First Pattern**: The command uses the current bundle (specified via --bundle) as default. Never requires direct `.specfact` paths - always use the CLI interface.
-
-**What it checks:**
-
-- Schema structure validation
-- Example generation test
-- Backward compatibility (if previous version provided)
-
-### Check Backward Compatibility
-
-Compare two specification versions:
-
-```bash
-specfact spec backward-compat api/openapi.v1.yaml api/openapi.v2.yaml
-```
-
-**Output:**
-
-- ✓ Compatible - No breaking changes detected
-- ✗ Breaking changes - Lists incompatible changes
-
-### Generate Test Suite
-
-Auto-generate contract tests from specification. Can generate for a single file or all contracts in a bundle:
-
-```bash
-# Generate for a single spec file
-specfact spec generate-tests api/openapi.yaml
-
-# Generate to custom location
-specfact spec generate-tests api/openapi.yaml --output tests/specmatic/
-
-# Generate tests for all contracts in active bundle
-specfact spec generate-tests --bundle legacy-api
-
-# Generate tests for all contracts in specific bundle
-specfact spec generate-tests --bundle legacy-api --output tests/contract/
-```
-
-**CLI-First Pattern**: Uses the current bundle (specified via --bundle). Never requires direct `.specfact` paths.
-
-### What Can You Do With Generated Tests?
-
-The tests generated by `spec generate-tests` are **executable contract tests** that validate your API implementation against your OpenAPI/AsyncAPI specification. Here's a complete walkthrough:
-
-#### Understanding Generated Tests
-
-When you run `specfact spec generate-tests`, Specmatic creates test files that:
-
-- **Validate request format**: Check that requests match the spec (headers, body, query params)
-- **Validate response format**: Verify responses match the spec (status codes, headers, body schema)
-- **Test all endpoints**: Ensure all endpoints defined in the spec are implemented
-- **Check data types**: Validate that data types and constraints are respected
-- **Property-based testing**: Automatically generate diverse test data to find edge cases
-
-#### Step-by-Step: Using Generated Tests
-
-**Step 1: Generate Tests from Your Contract**
-
-```bash
-# Generate tests for all contracts in your bundle
-specfact spec generate-tests --bundle my-api --output tests/contract/
-
-# Output:
-# [1/5] Generating test suite from: .specfact/projects/my-api/contracts/api.openapi.yaml
-# ✓ Test suite generated: tests/contract/
-# ...
-# ✓ Generated tests for 5 contract(s)
-```
-
-**Step 2: Review Generated Test Files**
-
-The tests are generated in the output directory (default: `.specfact/specmatic-tests/`):
-
-```bash
-# Check what was generated
-ls -la tests/contract/
-# Output shows Specmatic test files (format depends on Specmatic version)
-```
-
-**Step 3: Start Your API Server**
-
-Before running tests, start your API implementation:
-
-```bash
-# Example: Start FastAPI server
-python -m uvicorn main:app --port 8000
-
-# Or Flask
-python app.py
-
-# Or any other API server
-# Make sure it's running on the expected host/port
-```
-
-**Step 4: Run Tests Against Your API**
-
-Use Specmatic's test runner to execute the generated tests:
-
-```bash
-# Run tests against your running API
-specmatic test \
- --spec .specfact/projects/my-api/contracts/api.openapi.yaml \
- --host http://localhost:8000
-
-# Output:
-# ✓ GET /api/users - Request/Response match contract
-# ✓ POST /api/users - Request/Response match contract
-# ✗ GET /api/products - Response missing required field 'price'
-# ...
-```
-
-**Step 5: Fix Issues and Re-run**
-
-If tests fail, fix your API implementation and re-run:
-
-```bash
-# Fix the API code
-# ... make changes ...
-
-# Restart API server
-python -m uvicorn main:app --port 8000
-
-# Re-run tests
-specmatic test --spec ... --host http://localhost:8000
-```
-
-#### Complete Example: Contract-Driven Development Workflow
-
-Here's a full workflow from contract to tested implementation:
-
-```bash
-# 1. Import existing code and extract contracts
-specfact code import user-api --repo .
-
-# 2. Validate contracts are correct
-specfact spec validate --bundle user-api
-
-# Output:
-# [1/3] Validating specification: contracts/user-api.openapi.yaml
-# ✓ Specification is valid: user-api.openapi.yaml
-# ...
-
-# 3. Generate tests from validated contracts
-specfact spec generate-tests --bundle user-api --output tests/contract/
-
-# Output:
-# [1/3] Generating test suite from: contracts/user-api.openapi.yaml
-# ✓ Test suite generated: tests/contract/
-# ✓ Generated tests for 3 contract(s)
-
-# 4. Start your API server
-python -m uvicorn api.main:app --port 8000 &
-sleep 3 # Wait for server to start
-
-# 5. Run contract tests
-specmatic test \
- --spec .specfact/projects/user-api/contracts/user-api.openapi.yaml \
- --host http://localhost:8000
-
-# Output:
-# Running contract tests...
-# ✓ GET /api/users - Passed
-# ✓ POST /api/users - Passed
-# ✓ GET /api/users/{id} - Passed
-# All tests passed! ✓
-```
-
-#### CI/CD Integration Example
-
-Add contract testing to your CI/CD pipeline:
-
-```yaml
-# .github/workflows/contract-tests.yml
-name: Contract Tests
-
-on: [push, pull_request]
-
-jobs:
- contract-tests:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v3
-
- - name: Install Specmatic
- run: |
- curl https://docs.specmatic.io/install-specmatic.sh | bash
-
- - name: Install SpecFact CLI
- run: pip install specfact-cli
-
- - name: Generate contract tests
- run: |
- specfact spec generate-tests \
- --bundle my-api \
- --output tests/contract/ \
- --no-interactive
-
- - name: Start API server
- run: |
- python -m uvicorn main:app --port 8000 &
- sleep 5
-
- - name: Run contract tests
- run: |
- specmatic test \
- --spec .specfact/projects/my-api/contracts/api.openapi.yaml \
- --host http://localhost:8000
-```
-
-#### Testing Against Mock Servers
-
-You can also test your client code against Specmatic mock servers:
-
-```bash
-# Terminal 1: Start mock server
-specfact spec mock --bundle my-api --port 9000
-
-# Terminal 2: Run your client code against mock
-python client.py # Your client code that calls the API
-
-# The mock server:
-# - Validates requests match the spec
-# - Returns spec-compliant responses
-# - Helps test client code without a real API
-```
-
-#### Benefits of Using Generated Tests
-
-1. **Automated Validation**: Catch contract violations automatically
-2. **Early Detection**: Find issues before deployment
-3. **Documentation**: Tests serve as executable examples
-4. **Confidence**: Ensure API changes don't break contracts
-5. **Integration Safety**: Prevent breaking changes between services
-6. **Property-Based Testing**: Automatically test edge cases and boundary conditions
-
-#### Troubleshooting Test Execution
-
-**Tests fail with "Connection refused":**
-
-```bash
-# Make sure your API server is running
-curl http://localhost:8000/health # Test server is up
-
-# Check the host/port in your test command matches your server
-specmatic test --spec ... --host http://localhost:8000
-```
-
-**Tests fail with "Response doesn't match contract":**
-
-```bash
-# Check what the actual response is
-curl -v http://localhost:8000/api/users
-
-# Compare with your OpenAPI spec
-# Fix your API implementation to match the spec
-```
-
-**Tests pass but you want to see details:**
-
-```bash
-# Use verbose mode (if supported by Specmatic version)
-specmatic test --spec ... --host ... --verbose
-```
-
-### Run Mock Server
-
-Start a mock server for development. Can use a single spec file or select from bundle contracts:
-
-```bash
-# Auto-detect spec file from current directory
-specfact spec mock
-
-# Specify spec file and port
-specfact spec mock --spec api/openapi.yaml --port 9000
-
-# Use examples mode (less strict)
-specfact spec mock --spec api/openapi.yaml --examples
-
-# Select contract from active bundle (interactive)
-specfact spec mock --bundle legacy-api
-
-# Use specific bundle (non-interactive, uses first contract)
-specfact spec mock --bundle legacy-api --no-interactive
-```
-
-**CLI-First Pattern**: Uses the current bundle (specified via --bundle). Interactive selection when multiple contracts available.
-
-**Mock server features:**
-
-- Serves API endpoints based on specification
-- Validates requests against spec
-- Returns example responses
-- Press Ctrl+C to stop
-
----
-
-## Integration with Other Commands
-
-Specmatic validation is automatically integrated into:
-
-### Import Command
-
-When importing code, SpecFact auto-detects and validates OpenAPI/AsyncAPI specs:
-
-```bash
-# Import with bundle
-specfact code import legacy-api --repo .
-
-# Automatically validates:
-# - Repo-level OpenAPI/AsyncAPI specs (openapi.yaml, asyncapi.yaml)
-# - Bundle contract files referenced in features
-# - Suggests starting mock server if API specs found
-```
-
-### Enforce Command
-
-SDD enforcement includes Specmatic validation for all contracts referenced in the bundle:
-
-```bash
-# Enforce SDD
-specfact govern enforce sdd --bundle legacy-api
-
-# Automatically validates:
-# - All contract files referenced in bundle features
-# - Includes validation results in enforcement report
-# - Reports deviations for invalid contracts
-```
-
-### Sync Command
-
-Repository sync validates specs before synchronization:
-
-```bash
-# Sync bridge
-specfact project sync bridge --bundle legacy-api --repo .
-
-# Automatically validates:
-# - OpenAPI/AsyncAPI specs before sync operation
-# - Prevents syncing invalid contracts
-# - Reports validation errors before proceeding
-```
-
----
-
-## How It Works
-
-### Architecture
-
-```text
-┌─────────────────────────────────────────────────────────┐
-│ SpecFact Complete Stack │
-├─────────────────────────────────────────────────────────┤
-│ │
-│ Layer 1: Code-Level Contracts (Current) │
-│ ├─ icontract: Function preconditions/postconditions │
-│ ├─ beartype: Runtime type validation │
-│ └─ CrossHair: Symbolic execution & counterexamples │
-│ │
-│ Layer 2: Service-Level Contracts (Specmatic) │
-│ ├─ OpenAPI/AsyncAPI validation │
-│ ├─ Backward compatibility checking │
-│ ├─ Mock server for development │
-│ └─ Contract testing automation │
-│ │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Integration Pattern
-
-SpecFact calls Specmatic via subprocess:
-
-1. **Check availability** - Verifies Specmatic CLI is in PATH
-2. **Execute command** - Runs Specmatic CLI with appropriate arguments
-3. **Parse results** - Extracts validation results and errors
-4. **Display output** - Shows results in SpecFact's rich console format
-
----
-
-## Examples
-
-### Example 1: Validate API Spec During Import
-
-```bash
-# Project has openapi.yaml
-specfact code import api-service --repo .
-
-# Output:
-# ✓ Import complete!
-# 🔍 Found 1 API specification file(s)
-# Validating openapi.yaml with Specmatic...
-# ✓ openapi.yaml is valid
-# Validated 3 bundle contract(s), 0 failed.
-# 💡 Tip: Run 'specfact spec mock --bundle api-service' to start a mock server for development
-```
-
-### Example 2: Check Breaking Changes
-
-```bash
-# Compare API versions
-specfact spec backward-compat api/v1/openapi.yaml api/v2/openapi.yaml
-
-# Output:
-# ✗ Breaking changes detected
-# Breaking Changes:
-# - Removed endpoint /api/v1/users
-# - Changed response schema for /api/v1/products
-```
-
-### Example 3: Development Workflow with Bundle
-
-```bash
-# 1. Validate all contracts in bundle (interactive selection)
-specfact spec validate --bundle api-service
-# Shows list of contracts, select by number or 'all'
-
-# 3. Start mock server from bundle (interactive selection)
-specfact spec mock --bundle api-service --port 9000
-
-# 4. In another terminal, test against mock
-curl http://localhost:9000/api/users
-
-# 5. Generate tests for all contracts
-specfact spec generate-tests --bundle api-service --output tests/
-```
-
-### Example 4: CI/CD Workflow (Non-Interactive)
-
-```bash
-# 1. Validate all contracts in bundle (non-interactive)
-specfact spec validate --bundle api-service --no-interactive
-
-# 2. Generate tests for all contracts
-specfact spec generate-tests --bundle api-service --output tests/ --no-interactive
-
-# 3. Run generated tests
-pytest tests/specmatic/
-```
-
----
-
-## Troubleshooting
-
-### Specmatic Not Found
-
-**Error:**
-
-```text
-✗ Specmatic not available: Specmatic CLI not found. Install from: https://docs.specmatic.io/
-```
-
-**Solution:**
-
-1. Install Specmatic from [https://docs.specmatic.io/](https://docs.specmatic.io/)
-2. Ensure `specmatic` is in your PATH
-3. Verify with: `specmatic --version`
-
-### Validation Failures
-
-**Error:**
-
-```text
-✗ Specification validation failed
-Errors:
- - Schema validation failed: missing required field 'info'
-```
-
-**Solution:**
-
-1. Check your OpenAPI/AsyncAPI spec format
-2. Validate with: `specmatic validate your-spec.yaml`
-3. Review Specmatic documentation for spec requirements
-
-### Mock Server Won't Start
-
-**Error:**
-
-```text
-✗ Failed to start mock server: Port 9000 already in use
-```
-
-**Solution:**
-
-1. Use a different port: `specfact spec mock --port 9001`
-2. Stop the existing server on that port
-3. Check for other processes: `lsof -i :9000`
-
----
-
-## Best Practices
-
-1. **Validate early** - Run `specfact spec validate` before committing spec changes
-2. **Check compatibility** - Use `specfact spec backward-compat` when updating API versions
-3. **Use mock servers** - Start mock servers during development to test integrations
-4. **Generate tests** - Auto-generate tests for CI/CD pipelines
-5. **Integrate in workflows** - Let SpecFact auto-validate specs during import/enforce/sync
-
----
-
-## See Also
-
-### Related Guides
-
-- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations
-- [Command Chains Reference](command-chains.md) - Complete workflows including [API Contract Development Chain](command-chains.md#4-api-contract-development-chain)
-- Common Tasks Index - Quick reference for API-related tasks
-- [Contract Testing Workflow](contract-testing-workflow.md) - Contract testing patterns
-
-### Related Commands
-
-- [Command Reference - Spec Commands](../reference/commands.md#spec-commands) - Full command documentation
-- [Command Reference - Contract Commands](../reference/commands.md#contract-commands) - Contract verification commands
-
-### Related Examples
-
-- [API Contract Development Examples](../examples/) - Real-world examples
-
-### External Documentation
-
-- **[Specmatic Official Docs](https://docs.specmatic.io/)** - Specmatic documentation
-- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI spec format
-- **[AsyncAPI Specification](https://www.asyncapi.com/)** - AsyncAPI spec format
-
----
+**Prerequisites:** [Specmatic API reference](https://docs.specfact.io/reference/specmatic/) on core for symbols; Specmatic installed per your stack.
-**Note**: Specmatic is an external tool and must be installed separately. SpecFact CLI provides integration but does not include Specmatic itself.
+**Full guide on the canonical modules docs site:** [Specmatic integration](https://modules.specfact.io/specmatic-integration/)
diff --git a/docs/guides/team-collaboration-workflow.md b/docs/guides/team-collaboration-workflow.md
index 467b16d3..a44b4da1 100644
--- a/docs/guides/team-collaboration-workflow.md
+++ b/docs/guides/team-collaboration-workflow.md
@@ -2,203 +2,15 @@
layout: default
title: Team Collaboration Workflow
permalink: /guides/team-collaboration-workflow/
+description: Handoff to team collaboration workflow on the modules documentation site.
redirect_from:
- /team-collaboration-workflow/
---
-# Team Collaboration Workflow
+# Team collaboration workflow
-> **Complete guide to using SpecFact CLI for team collaboration with persona-based workflows**
+Align distributed teams around SpecFact—shared bundles, review gates, and IDE prompts. The full collaboration patterns and examples are maintained on the modules documentation site.
----
-
-## Overview
-
-SpecFact CLI supports team collaboration through persona-based workflows where different roles (Product Owner, Architect, Developer) work on different aspects of the project using Markdown files. This guide explains when and how to use the team collaboration commands.
-
-**Related**: [Agile/Scrum Workflows](agile-scrum-workflows.md) - Complete persona-based collaboration guide
-
----
-
-## When to Use Team Collaboration Commands
-
-Use these commands when:
-
-- **Multiple team members** need to work on the same project bundle
-- **Different roles** (Product Owner, Architect, Developer) need to edit different sections
-- **Concurrent editing** needs to be managed safely
-- **Version control** integration is needed for team workflows
-
----
-
-## Core Commands
-
-### `project init-personas`
-
-Initialize persona definitions for a project bundle.
-
-**When to use**: First-time setup for team collaboration.
-
-**Example**:
-
-```bash
-specfact project init-personas --bundle my-project
-```
-
-**Related**: [Agile/Scrum Workflows - Persona Setup](agile-scrum-workflows.md#persona-based-workflows)
-
----
-
-### `project export`
-
-Export persona-specific Markdown artifacts for editing.
-
-**When to use**: When a team member needs to edit their role-specific sections.
-
-**Example**:
-
-```bash
-# Export Product Owner view
-specfact project export --bundle my-project --persona product-owner
-
-# Export Developer view
-specfact project export --bundle my-project --persona developer
-
-# Export Architect view
-specfact project export --bundle my-project --persona architect
-```
-
-**Workflow**: Export → Edit in Markdown → Import back
-
-**Related**: [Agile/Scrum Workflows - Exporting Persona Artifacts](agile-scrum-workflows.md#exporting-persona-artifacts)
-
----
-
-### `project import`
-
-Import persona edits from Markdown files back into the project bundle.
-
-**When to use**: After editing exported Markdown files.
-
-**Example**:
-
-```bash
-# Import Product Owner edits
-specfact project import --bundle my-project --persona product-owner --source docs/backlog.md
-
-# Dry-run to validate without applying
-specfact project import --bundle my-project --persona product-owner --source docs/backlog.md --dry-run
-```
-
-**Workflow**: Export → Edit → Import → Validate
-
-**Related**: [Agile/Scrum Workflows - Importing Persona Edits](agile-scrum-workflows.md#importing-persona-edits)
-
----
-
-### `project lock` / `project unlock`
-
-Lock sections to prevent concurrent edits.
-
-**When to use**: When multiple team members might edit the same section simultaneously.
-
-**Example**:
-
-```bash
-# Lock a section for editing
-specfact project lock --bundle my-project --section idea --persona product-owner
-
-# Edit and import
-specfact project export --bundle my-project --persona product-owner
-# ... edit exported file ...
-specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-# Unlock when done
-specfact project unlock --bundle my-project --section idea
-```
-
-**Workflow**: Lock → Export → Edit → Import → Unlock
-
-**Related**: [Agile/Scrum Workflows - Section Locking](agile-scrum-workflows.md#section-locking)
-
----
-
-### `project locks`
-
-List all locked sections.
-
-**When to use**: Before starting work to see what's locked.
-
-**Example**:
-
-```bash
-specfact project locks --bundle my-project
-```
-
-**Related**: [Agile/Scrum Workflows - Checking Locks](agile-scrum-workflows.md#checking-locks)
-
----
-
-## Complete Workflow Example
-
-### Scenario: Product Owner Updates Backlog
-
-```bash
-# 1. Check what's locked
-specfact project locks --bundle my-project
-
-# 2. Lock the section you need
-specfact project lock --bundle my-project --section idea --persona product-owner
-
-# 3. Export your view
-specfact project export --bundle my-project --persona product-owner --output backlog.md
-
-# 4. Edit backlog.md in your preferred editor
-
-# 5. Import changes back
-specfact project import --bundle my-project --persona product-owner --source backlog.md
-
-# 6. Unlock the section
-specfact project unlock --bundle my-project --section idea
-```
-
----
-
-## Integration with Version Management
-
-Team collaboration integrates with version management:
-
-```bash
-# After importing changes, check if version bump is needed
-specfact project version check --bundle my-project
-
-# If needed, bump version
-specfact project version bump --bundle my-project --type minor
-```
-
-**Related**: [Project Version Management](../reference/commands.md#project-version)
-
----
-
-## Integration with Command Chains
-
-Team collaboration commands are part of the **Plan Promotion & Release Chain**:
-
-1. Export persona views
-2. Edit in Markdown
-3. Import back
-4. Review plan
-5. Enforce SDD
-6. Promote plan
-7. Bump version
-
-**Related**: [Plan Promotion & Release Chain](command-chains.md#5-plan-promotion--release-chain)
-
----
-
-## See Also
+**Prerequisites:** [Module categories](https://docs.specfact.io/reference/module-categories/) for how bundles group; Git hosting for your specs.
-- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Complete persona-based collaboration guide
-- [Command Chains Reference](command-chains.md) - Complete workflows
-- Common Tasks Index - Quick reference
-- [Project Commands Reference](../reference/commands.md#project---project-bundle-management) - Complete command documentation
+**Full guide on the canonical modules docs site:** [Team collaboration workflow](https://modules.specfact.io/team-collaboration-workflow/)
diff --git a/docs/reference/README.md b/docs/reference/README.md
index d722eddd..65ebbda0 100644
--- a/docs/reference/README.md
+++ b/docs/reference/README.md
@@ -13,6 +13,7 @@ For bundle-specific deep command guides and runbooks, use the canonical modules
## Core Reference Topics
+- **[Documentation URL contract](documentation-url-contract.md)** - How core and modules sites relate; rules for cross-site links
- **[Commands](commands.md)** - Exact grouped command topology and migration mapping
- **[Command Syntax Policy](command-syntax-policy.md)** - Source-of-truth argument syntax conventions for docs
- **[Architecture](../architecture/overview.md)** - Technical design, module structure, and internals
diff --git a/docs/reference/core-to-modules-handoff-urls.md b/docs/reference/core-to-modules-handoff-urls.md
new file mode 100644
index 00000000..47ba71ea
--- /dev/null
+++ b/docs/reference/core-to-modules-handoff-urls.md
@@ -0,0 +1,33 @@
+---
+layout: default
+title: Core handoff pages to modules canonical URLs
+permalink: /reference/core-to-modules-handoff-urls/
+description: Checklist mapping docs.specfact.io handoff pages to modules.specfact.io canonical permalinks (docs-07).
+---
+
+# Core handoff pages → modules canonical URLs
+
+Each row lists the **core** published path (`docs.specfact.io`) and the **modules** URL that owns the full guide. Authoritative cross-site rules: [Documentation URL contract](documentation-url-contract.md) and [modules documentation-url-contract](https://modules.specfact.io/reference/documentation-url-contract/).
+
+| Core permalink | Modules canonical URL |
+| --- | --- |
+| `/guides/brownfield-engineer/` | `https://modules.specfact.io/brownfield-engineer/` |
+| `/guides/brownfield-journey/` | `https://modules.specfact.io/brownfield-journey/` |
+| `/guides/brownfield-faq/` | `https://modules.specfact.io/brownfield-faq/` |
+| `/guides/brownfield-roi/` | `https://modules.specfact.io/brownfield-roi/` |
+| `/guides/backlog-refinement/` | `https://modules.specfact.io/bundles/backlog/refinement/` |
+| `/guides/backlog-delta-commands/` | `https://modules.specfact.io/bundles/backlog/delta/` |
+| `/guides/backlog-dependency-analysis/` | `https://modules.specfact.io/bundles/backlog/dependency-analysis/` |
+| `/guides/devops-adapter-integration/` | `https://modules.specfact.io/integrations/devops-adapter-overview/` |
+| `/guides/import-features/` | `https://modules.specfact.io/bundles/project/import-migration/` |
+| `/guides/project-devops-flow/` | `https://modules.specfact.io/bundles/project/devops-flow/` |
+| `/guides/sidecar-validation/` | `https://modules.specfact.io/bundles/codebase/sidecar-validation/` |
+| `/guides/policy-engine-commands/` | `https://modules.specfact.io/bundles/backlog/policy-engine/` |
+| `/guides/custom-field-mapping/` | `https://modules.specfact.io/guides/custom-field-mapping/` |
+| `/guides/contract-testing-workflow/` | `https://modules.specfact.io/contract-testing-workflow/` |
+| `/guides/specmatic-integration/` | `https://modules.specfact.io/specmatic-integration/` |
+| `/guides/agile-scrum-workflows/` | `https://modules.specfact.io/guides/agile-scrum-workflows/` |
+| `/guides/team-collaboration-workflow/` | `https://modules.specfact.io/team-collaboration-workflow/` |
+| `/getting-started/tutorial-backlog-quickstart-demo/` | `https://modules.specfact.io/getting-started/tutorial-backlog-quickstart-demo/` |
+| `/getting-started/tutorial-backlog-refine-ai-ide/` | `https://modules.specfact.io/getting-started/tutorial-backlog-refine-ai-ide/` |
+| `/getting-started/tutorial-daily-standup-sprint-review/` | `https://modules.specfact.io/getting-started/tutorial-daily-standup-sprint-review/` |
diff --git a/docs/reference/documentation-url-contract.md b/docs/reference/documentation-url-contract.md
new file mode 100644
index 00000000..680476e6
--- /dev/null
+++ b/docs/reference/documentation-url-contract.md
@@ -0,0 +1,27 @@
+---
+layout: default
+title: Documentation URL contract (core and modules)
+permalink: /reference/documentation-url-contract/
+description: Rules for linking between docs.specfact.io and modules.specfact.io; canonical ownership of paths.
+---
+
+# Documentation URL contract (core and modules)
+
+The **authoritative** URL and ownership rules for **both** documentation sites are maintained in the **modules** repository so bundle paths, `redirect_from` history, and permalink policy stay in one place.
+
+## Canonical reference
+
+- **[Core and modules docs URL contract](https://modules.specfact.io/reference/documentation-url-contract/)** (`specfact-cli-modules`) — read this before changing cross-site links or permalinks.
+
+## Quick rules for core contributors
+
+1. **Do not assume** `https://modules.specfact.io/guides/<name>/` exists because core uses `/guides/<name>/`. Modules uses `/guides/...`, `/bundles/.../`, `/integrations/.../`, and root paths such as `/brownfield-engineer/` depending on the page—**always** verify the target file’s `permalink` in `specfact-cli-modules`.
+2. **Handoff pages** (see OpenSpec `docs-07-core-handoff-conversion`) must point to the **modules canonical URL** for each topic, with a short summary and prerequisites on core.
+3. **Internal core links** must continue to resolve on `docs.specfact.io` per published `permalink` (docs review gate / parity tests).
+
+## Repositories
+
+| Concern | Repository |
+| --- | --- |
+| Core CLI docs source | `nold-ai/specfact-cli` → `docs/` |
+| Modules docs source | `nold-ai/specfact-cli-modules` → `docs/` |
diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md
index 647bfda5..615446a5 100644
--- a/openspec/CHANGE_ORDER.md
+++ b/openspec/CHANGE_ORDER.md
@@ -123,7 +123,7 @@ The 2026-03-23 docs-refactoring-beginner-to-enterprise plan adds 8 changes acros
All specfact-cli changes sync to GitHub as User Story issues under parent Feature [#356](https://github.com/nold-ai/specfact-cli/issues/356) with labels: `documentation`, `change-proposal`, `openspec`.
-Cross-repo dependency: `docs-07-core-handoff-conversion` depends on `specfact-cli-modules/docs-06-modules-site-ia-restructure` (target pages must exist before redirects are created).
+Cross-repo dependency: `docs-07-core-handoff-conversion` depends on `specfact-cli-modules/docs-06-modules-site-ia-restructure` (target pages must exist before redirects are created). URL policy and permalink rules: `https://modules.specfact.io/reference/documentation-url-contract/` (authoritative); core summary: `docs/reference/documentation-url-contract.md`.
### Marketplace (module distribution)
diff --git a/openspec/changes/docs-07-core-handoff-conversion/proposal.md b/openspec/changes/docs-07-core-handoff-conversion/proposal.md
index 2e1c8aa5..7768b813 100644
--- a/openspec/changes/docs-07-core-handoff-conversion/proposal.md
+++ b/openspec/changes/docs-07-core-handoff-conversion/proposal.md
@@ -20,7 +20,8 @@ The core docs site currently has 20+ pages that contain full duplicate content o
## Impact
- Affected docs (20 files): `guides/brownfield-engineer.md`, `guides/brownfield-journey.md`, `guides/brownfield-faq.md`, `guides/brownfield-roi.md`, `guides/backlog-refinement.md`, `guides/backlog-delta-commands.md`, `guides/backlog-dependency-analysis.md`, `guides/devops-adapter-integration.md`, `guides/custom-field-mapping.md`, `guides/import-features.md`, `guides/policy-engine-commands.md`, `guides/project-devops-flow.md`, `guides/sidecar-validation.md`, `guides/contract-testing-workflow.md`, `guides/specmatic-integration.md`, `guides/agile-scrum-workflows.md`, `guides/team-collaboration-workflow.md`, `getting-started/tutorial-backlog-quickstart-demo.md`, `getting-started/tutorial-backlog-refine-ai-ide.md`, `getting-started/tutorial-daily-standup-sprint-review.md`
-- Depends on: `docs-06-modules-site-ia-restructure` (target pages must exist on modules site)
+- Depends on: `docs-06-modules-site-ia-restructure` (target pages must exist on modules site; includes `/reference/documentation-url-contract/` and legacy `/guides/` redirects on modules)
+- Canonical links MUST use real modules `permalink` values (see `docs/reference/documentation-url-contract.md` on core and modules)
- User-facing: users are directed to the canonical single source of truth for each guide
## Source Tracking
diff --git a/openspec/changes/docs-07-core-handoff-conversion/specs/documentation-alignment/spec.md b/openspec/changes/docs-07-core-handoff-conversion/specs/documentation-alignment/spec.md
index 6f955d24..efb955e5 100644
--- a/openspec/changes/docs-07-core-handoff-conversion/specs/documentation-alignment/spec.md
+++ b/openspec/changes/docs-07-core-handoff-conversion/specs/documentation-alignment/spec.md
@@ -1,25 +1,37 @@
-# Capability Delta: documentation-alignment (handoff conversion)
+# Delta: documentation-alignment (handoff conversion)
-Core handoff pages are converted from full duplicate content to thin summaries with canonical links.
+Extends `documentation-alignment` so core handoff pages are thin summaries with canonical links to modules.
-## Scenarios
+## ADDED Requirements
-### Scenario: Handoff page contains summary and canonical link
+### Requirement: Core handoff pages are thin summaries with a canonical modules link
-Given a core docs page that was previously a full duplicate of module content
-When the page is converted to a handoff redirect
-Then it contains a 1-2 paragraph summary of what the guide covers
-And it contains a prominent canonical link to the modules site URL
-And it does NOT contain the full guide content
+Core docs pages that previously duplicated module-owned guides SHALL contain only a short summary, prerequisites, and a prominent link to the canonical URL on `modules.specfact.io` (per `permalink` in `specfact-cli-modules`), not the full guide body.
-### Scenario: Old URLs are preserved via redirect
+#### Scenario: Handoff page structure
-Given a handoff page at its original URL
-When a user visits the original URL
-Then the page loads (not 404) and displays the summary with canonical link
+- **WHEN** a reader opens a converted handoff page on `docs.specfact.io`
+- **THEN** the page includes a brief summary of the topic
+- **AND** it includes a prerequisites note
+- **AND** it includes a prominent link to the full guide on the canonical modules docs site
+- **AND** it does not include the duplicated long-form guide content owned by modules
-### Scenario: Each handoff page maps to a valid modules target
+### Requirement: Legacy URLs remain reachable
-Given the 20 identified handoff pages
-When each is converted
-Then each canonical link points to a page that exists on modules.specfact.io
+Handoff pages that previously published under alternate paths SHALL preserve `redirect_from` entries so old bookmarks do not 404.
+
+#### Scenario: Redirect metadata preserved where applicable
+
+- **WHEN** a handoff page had `redirect_from` for legacy paths
+- **THEN** those entries remain in front matter after conversion
+- **AND** the published URL still serves the thin handoff page
+
+### Requirement: Canonical link targets match modules permalinks
+
+Each converted page’s canonical link SHALL match the modules documentation `permalink` for that topic (which may be `/bundles/.../`, `/guides/.../`, `/integrations/.../`, or a root path), not an assumed mirror of the core `/guides/<name>/` path.
+
+#### Scenario: URL contract compliance
+
+- **WHEN** authors map core handoff pages to modules URLs
+- **THEN** they use the checklist and `documentation-url-contract` rules
+- **AND** each link targets the verified modules canonical URL for that guide
diff --git a/openspec/changes/docs-07-core-handoff-conversion/tasks.md b/openspec/changes/docs-07-core-handoff-conversion/tasks.md
index 1d61aecf..2fc7a535 100644
--- a/openspec/changes/docs-07-core-handoff-conversion/tasks.md
+++ b/openspec/changes/docs-07-core-handoff-conversion/tasks.md
@@ -1,25 +1,25 @@
## 1. Change Setup And Spec Deltas
-- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-07-core-handoff-conversion` entry
-- [ ] 1.2 Add `documentation-alignment` delta for handoff-to-redirect conversion pattern
+- [x] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-07-core-handoff-conversion` entry
+- [x] 1.2 Add `documentation-alignment` delta for handoff-to-redirect conversion pattern
## 2. Verify Target Pages Exist
-- [ ] 2.1 Verify that docs-06-modules-site-ia-restructure has created all target pages on the modules site before proceeding
-- [ ] 2.2 Create a checklist mapping each core handoff file to its modules target URL
+- [x] 2.1 Verify that docs-06-modules-site-ia-restructure has created all target pages on the modules site before proceeding (use `docs/reference/documentation-url-contract.md` on each repo and each target file’s `permalink` in `specfact-cli-modules`)
+- [x] 2.2 Create a checklist mapping each core handoff file to its modules target URL (do not assume `/guides/` on modules matches core; prefer bundle paths and `/reference/documentation-url-contract/` on modules for authoritative rules)
## 3. Convert Handoff Pages
-- [ ] 3.1 Convert brownfield guides (4 files): brownfield-engineer, brownfield-journey, brownfield-faq, brownfield-roi
-- [ ] 3.2 Convert backlog guides (3 files): backlog-refinement, backlog-delta-commands, backlog-dependency-analysis
-- [ ] 3.3 Convert project/code guides (4 files): devops-adapter-integration, import-features, project-devops-flow, sidecar-validation
-- [ ] 3.4 Convert policy/spec guides (3 files): policy-engine-commands, custom-field-mapping, contract-testing-workflow
-- [ ] 3.5 Convert integration guides (2 files): specmatic-integration, agile-scrum-workflows, team-collaboration-workflow
-- [ ] 3.6 Convert getting-started tutorials (3 files): tutorial-backlog-quickstart-demo, tutorial-backlog-refine-ai-ide, tutorial-daily-standup-sprint-review
+- [x] 3.1 Convert brownfield guides (4 files): brownfield-engineer, brownfield-journey, brownfield-faq, brownfield-roi
+- [x] 3.2 Convert backlog guides (3 files): backlog-refinement, backlog-delta-commands, backlog-dependency-analysis
+- [x] 3.3 Convert project/code guides (4 files): devops-adapter-integration, import-features, project-devops-flow, sidecar-validation
+- [x] 3.4 Convert policy/spec guides (3 files): policy-engine-commands, custom-field-mapping, contract-testing-workflow
+- [x] 3.5 Convert integration guides (2 files): specmatic-integration, agile-scrum-workflows, team-collaboration-workflow
+- [x] 3.6 Convert getting-started tutorials (3 files): tutorial-backlog-quickstart-demo, tutorial-backlog-refine-ai-ide, tutorial-daily-standup-sprint-review
## 4. Verification
-- [ ] 4.1 Run `bundle exec jekyll build` and verify zero warnings
-- [ ] 4.2 Verify all redirect entries resolve correctly
-- [ ] 4.3 Verify each converted page contains: summary paragraph, prerequisites note, canonical link
-- [ ] 4.4 Run repo quality gates on touched files
+- [x] 4.1 Run `bundle exec jekyll build` and verify zero warnings
+- [x] 4.2 Verify all redirect entries resolve correctly
+- [x] 4.3 Verify each converted page contains: summary paragraph, prerequisites note, canonical link
+- [x] 4.4 Run repo quality gates on touched files
diff --git a/openspec/config.yaml b/openspec/config.yaml
index cd9c00bf..524f18ed 100644
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -33,7 +33,8 @@ context: |
Documentation (critical for every change): User-facing docs are published at https://docs.specfact.io
(GitHub Pages). Source: docs/ with Jekyll front-matter (layout, title, permalink, description),
docs/index.md as landing, docs/_layouts/default.html for sidebar/menu navigation. README.md is the repo
- entry point.
+ entry point. Cross-site links to https://modules.specfact.io must use each target page’s real permalink
+ in specfact-cli-modules (see docs/reference/documentation-url-contract.md); do not mirror core /guides/ paths onto modules by assumption.
- Every change must include documentation research and review:
- (1) Identifies affected documentation: docs/ (reference, guides, adapters, getting-started),
README.md, docs/index.md.
diff --git a/openspec/specs/documentation-alignment/spec.md b/openspec/specs/documentation-alignment/spec.md
index 843403f1..d31e6319 100644
--- a/openspec/specs/documentation-alignment/spec.md
+++ b/openspec/specs/documentation-alignment/spec.md
@@ -148,3 +148,13 @@ The documentation workflow SHALL automatically fix low-risk Markdown issues duri
- **AND** any auto-fixed Markdown files are re-staged automatically
- **AND** markdown lint still runs afterward to fail on remaining non-fixable issues
+### Requirement: Cross-site links to modules docs use real published paths
+
+Authored links from `specfact-cli` docs to `https://modules.specfact.io/...` SHALL target the modules page’s actual published `permalink` (or default-derived path), and SHALL NOT assume the same path shape as core docs (for example `/guides/<name>/` on core does not imply `/guides/<name>/` on modules).
+
+#### Scenario: Contributor adds a handoff or reference link to modules
+
+- **WHEN** a contributor adds or updates a link to the canonical modules docs site
+- **THEN** the path segment matches the target file’s `permalink` in `specfact-cli-modules` or the URL contract reference
+- **AND** contributors can discover rules from `docs/reference/documentation-url-contract.md` on the core site
+
diff --git a/openspec/specs/module-docs-ownership/spec.md b/openspec/specs/module-docs-ownership/spec.md
index 20e08a92..5a806ae4 100644
--- a/openspec/specs/module-docs-ownership/spec.md
+++ b/openspec/specs/module-docs-ownership/spec.md
@@ -24,3 +24,12 @@ Any live module-specific guide or reference page that remains in `specfact-cli`
- **THEN** the page states whether it is a core-owned overview or a temporary handoff page
- **AND** the page links the reader to the canonical modules docs destination when module-specific deep guidance lives there.
+### Requirement: Canonical modules URLs are discoverable from core docs
+
+The core documentation set SHALL include a short reference page that explains the core vs modules URL relationship and points to the authoritative contract on `modules.specfact.io`.
+
+#### Scenario: Contributor looks up how to link to modules
+
+- **WHEN** a contributor needs to add or verify a cross-site link
+- **THEN** they can open `docs/reference/documentation-url-contract.md` in this repository for obligations and a link to the full contract on the modules site
+