Migration note: Migrated from ADR-0028 on 2026-05-02 per ADR-0047. Original file retained at docs/adr/0028-ado-board-single-source-of-truth.md with deprecation banner.

GOV-0003: ADO Board as Single Source of Truth and WI-First Branching Policy

Sources

• ADR-0028: ADO Board as Single Source of Truth and WI-First Branching Policy (2026-04-07)

Field	Value
ID	GOV-0003
Date	2026-04-07
Status	Accepted
Author	Ben Peries
Phases	All
ADO WI	#135
Class	security/GOV

Context

During a board hygiene audit on 2026-04-07, approximately 100 work items were found stuck in To Do state with no linked PRs. Work had shipped but the board never reflected it. Additionally, several PRs were opened without any linked work item, making it impossible to trace why a change was made.

Two compounding problems were identified:

1. Feature and release tracking was being considered for wiki/docs files rather than the board. This platform adopts Agile as its work management philosophy, currently implemented through Scrum in ADO with sprints, Product Backlog Items, and area paths. However, it is acknowledged that Scrum was designed for human teams with sprint ceremonies and velocity tracking. Its overhead model may not be optimal for a single-operator platform evolving toward agentic AI operations. The board-as-single-source-of-truth decision holds regardless of which Agile framework is in use. If the Scrum implementation evolves in a future ADR, the board discipline remains the correct pattern. Tracking work outside the board, regardless of format, creates a second source of truth that diverges from reality over time and undermines sprint integrity.

2. No enforcement mechanism existed to ensure a work item was created before branching. Claude Code, when instructed to create a branch, will do so without verifying a WI existed first.

This platform is also designed for eventual multi-operator and agentic use. Any enforcement mechanism must work across team members and AI agents without manual replication.

Honest Assessment — The Agentic Gap

This platform is being built toward fully agentic AI operations. That goal makes this limitation critical to document explicitly.

Claude Code, when instructed to create a branch, will do so. It does not independently verify that a work item exists before acting. If a human operator says "create a branch and fix this", Claude Code executes. The WI-first rule in CLAUDE.md is a nudge, not a gate. An operator -- or an AI agent acting on operator instruction -- can bypass it in a single sentence.

This is the fundamental challenge of agentic AI in DevOps today: AI agents are compliance-aware but not compliance-enforcing. They follow rules when the rules are visible and no conflicting instruction exists. They do not enforce rules against the operator who controls them.

The only controls that hold against agentic bypass are platform-level gates that exist outside the AI layer entirely: ADO branch policy, pipeline checks, and repo protection rules. These cannot be overridden by conversation.

As Archon evolves toward autonomous agent orchestration, every process control must be evaluated against this question: does this control survive an AI agent acting without human review? If the answer is no, a platform-level gate is required alongside it.

This ADR is the first explicit acknowledgment of that design principle in the Archon Platform.

Decision

The ADO board is the single source of truth for all work tracking. No feature lists, release logs, or work state tracking belong in wiki or documentation files. The board reflects reality at all times.

A WI-first branching policy is enforced at every layer of the stack.

The changelog at docs/changelog.md is derived from closed WIs and merged PRs per sprint. It is an output of the board, not a parallel tracking system.

Enforcement Stack

Defense in depth. No single layer is sufficient alone.

Layer	Mechanism	Bypass Risk
Hardest	ADO branch policy on main — Check for linked work items	Cannot be bypassed
Strong	Pipeline gate — fail build if PR has no linked WI	Bypassed only if pipeline skipped
Medium	CLAUDE.md hard constraint — WI verification before branch creation	Bypassed if overridden in session
Advisory	ccagnt-reviewer hard rule — reject PRs with no linked WI	Bypassed if agent not run

All four layers are implemented. The ADO branch policy is the authoritative gate.

WI-First Workflow

Every change follows this sequence without exception:

1. Create WI: az boards work-item create --type Task --title "..." --project archon-platform
2. Create branch: git checkout -b type/short-description
3. Open PR with WI linked: az repos pr create --title "..." --work-items

This applies to all branch types: feat/, fix/, chore/, docs/, adr/, hotfix/. No exceptions. A 30-second WI creation is not optional for small changes. The hygiene debt from skipping this is demonstrated by the 100-item backlog audit.

CLAUDE.md as Team Enforcement Mechanism

Repo-level CLAUDE.md files are the shared constraint layer for AI-assisted development. Every team member who clones the repo gets the constraints automatically. Git handles distribution. No manual replication needed.

The personal ~/.claude/CLAUDE.md is for individual preferences only. The repo CLAUDE.md is the team contract.

Multi-Operator Onboarding

When a new operator joins the platform, an onboarding script handles local Claude Code wiring. The repo constraints are already in place via CLAUDE.md. The script ensures the local environment can consume them correctly.

Onboarding script responsibilities: - Configure ~/.claude/settings.json with standard model and cost settings - Set up ADO CLI auth via az devops configure - Set up Infisical CLI and trust the self-signed cert - Clone all 6 repos to ~/homelab/repos/ - Verify kubectl config, SSH keys, WireGuard access - Install ccusage and configure daily cron export

The onboarding script lives at scripts/onboard.sh in archon-platform and is version-controlled.

Alternatives Considered

Option A: Feature tracking in docs/internal/features.md Rejected. Creates a second source of truth that diverges from the board. Requires manual synchronization. Does not integrate with sprint velocity or changelog generation.

Option B: Board-only with derived changelog (chosen) The board reflects reality. Changelog is auto-generated from closed WIs per sprint. Single source of truth. Integrates with ADO pipeline and ccagnt-planner enforcement.

Option C: Hybrid wiki and board Rejected. Hybrid systems always drift. One system wins over time and the other becomes stale. Better to choose one explicitly.

On CLAUDE.md enforcement alone: CLAUDE.md is a medium-strength control only. Claude Code reads it at session start but a human can override it in conversation. It is necessary but not sufficient. The ADO branch policy is the hard gate that cannot be bypassed regardless of operator or AI behavior.

Consequences

• ADO branch policy "Check for linked work items" enabled on main in all 6 repos (confirmed present)
• ccagnt-reviewer updated with hard rule: reject PRs with no linked WI
• ccagnt-planner updated to flag WIs still open after their PR merges
• CLAUDE.md in all 6 repos updated with WI-first hard constraint
• Onboarding script scaffold created at scripts/onboard.sh in archon-platform
• docs/internal/features.md not created -- board replaces it
• Bulk close of stale To Do WIs with no linked PRs completed 2026-04-07

Related ADRs

• GOV-0002: ADO Project Consolidation and Board Structure (extended by this ADR)