FDD Editor — Round-Trip

Functional Design Documents live in two places at once: structured fields on an Azure DevOps work item, and a Word document on SharePoint that business stakeholders actually review. Today the trip between the two is a manual copy-paste exercise with no audit trail and no guarantee that the version a PO just signed off on matches the work item it came from. FDD Editor automates the round-trip: it exports the canonical FDD fields to a Word .docx in a configured SharePoint library, detects reviewer edits via a Microsoft Graph webhook, surfaces a diff for the Product Owner, and applies all changes back to the work item in a single idempotent operation — with strict HTML fidelity enforced by a locked whitelist and every action recorded to a 2-year audit archive.

What you get

• Round-trip authoring. Click Export to Word on the FDD tab to generate a canonical .docx from the work item's FDD fields and stage it in SharePoint. Reviewers edit in Word for the Web (no plugin to install). When they save, the backend's Graph webhook fires, the extension parses the document, and the Product Owner sees a side-by-side change preview. One click applies the whole change-set to the work item — all-or-nothing, never partial.

• Audit trail. Every export, import, and cancel operation writes a structured event to Azure Application Insights and a 2-year append-blob archive. The Product Owner who approved an import is captured in the work item History entry, satisfying the four-eyes permission split (PRD §13: Export.Trigger is broad, Import.Approve is restricted to a nominated approver group).

• Strict HTML fidelity. The HTML whitelist (PRD §10) is the contract: the sanitizer preserves <p>, <br>, <strong>, <em>, <ul>, <ol>, <li>, and <a href> with http(s) schemes only. Headings are demoted to <p><strong>. Tables, images, inline styles, and Word's w: / o: namespaces are stripped — and every stripped element is surfaced in the preview dialog as an Unmapped content warning before the PO commits, so there is no silent data drift.

Prerequisites

This extension is the UI half of a two-component system. To run it you also need the backend Azure Function and supporting Azure resources deployed into your own tenant.

• Azure subscription with these resource providers registered: Microsoft.Web (Function App + Consumption plan), Microsoft.KeyVault (OAuth secret storage), Microsoft.Storage (audit-archive blob container), Microsoft.Insights (Application Insights). The full topology ships in infra/main.bicep.

• Microsoft Graph App Registration with Sites.Selected and Files.ReadWrite.All application permissions. Sites.Selected requires tenant-admin consent and a per-site grant on each SharePoint site you configure. See docs/pilot-onboarding.md for the full walkthrough.

• Azure DevOps project with the canonical five FDD fields available on the work item type: Columbus.FDD.Overview, Columbus.FDD.AcceptanceCriteria, Columbus.FDD.Assumptions, Columbus.FDD.Dependencies, Columbus.FDD.Risks. Field XML is provided in the pilot-onboarding pack.

• A Columbus.FDD security group nominated to hold the Import.Approve permission, per PRD §13 and ADR-0003. By default this is Project Administrators plus the nominated POs; the project-level config page lets you override.

Installation & configuration

The condensed flow:

1. Deploy infra/main.bicep into a resource group in your Azure subscription.
2. Install this extension into your Azure DevOps organization (private publisher install during pilot; public Marketplace once verified).
3. Open Project Settings → FDD Editor in any project that should use it. Paste the backend's public URL and the SharePoint site + drive + archive folder IDs. The page tests the connection, shows a success card, and reminds you to copy the values into the Function App's App Settings (manual step in v1; automation is tracked for v1.1).
4. Open any work item, click the FDD tab, and Export to Word.

The full walkthrough — including Sites.Selected grant scripts, App Registration scopes, and the field XML — is in docs/pilot-onboarding.md.

Privacy & data residency

Your FDD content never leaves your tenant. The extension calls only your own backend Function App, which in turn talks only to your Azure DevOps organization and your configured SharePoint site via Microsoft Graph. The Function App, Key Vault, audit-archive Storage Account, and Application Insights instance all live in your Azure subscription. Columbus AI Group runs no shared services and receives no telemetry from your installation.

Audit-log retention is 90 days hot in Application Insights plus 2 years in cool-tier blob storage (configurable via the Bicep parameter file).

Support

• Issues, feature requests, and discussion: https://github.com/ThomasHelenius/ado-fdd-editor/issues
• Source code, releases, and changelog: https://github.com/ThomasHelenius/ado-fdd-editor

Version control & changelog

The PRD (docs/ADO-FDD-Editor-PRD-v2.0.md) is locked at v2.0.0 against an external Design Lock document and an interactive POC. Substantive changes require a Change Request work item; editorial fixes are free. Extension versions follow the PRD's version-control procedure: additive changes bump the minor, breaking changes bump the major. Tagged releases are visible on the GitHub repo:

https://github.com/ThomasHelenius/ado-fdd-editor