ADO Board Hygiene¶

Established 2026-04-19. Applies to all agents and sessions in the Archon Platform project.

Problem This Solves¶

Work items created without a sprint or area path are invisible on the ADO board and sprint timeline. Before 2026-04-19, all ~80 open WIs were at the root iteration path (archon-platform) and most had no sub-area path, causing the sprint board to appear empty despite active work.

WI Creation Checklist¶

Every work item created by any agent or operator must include all of the following:

Field	Rule
`--area`	Never root. Always assign to a sub-area (see guide below).
`--iteration`	Never root. Always set to current active sprint (see lookup below).
`--type`	`Task` for implementation work; `Bug` for defects; `Feature` for epics.
`--fields System.Tags`	At least one tag.
`--state`	`To Do` for new Tasks; `Active` for Features/Stories started immediately.

Area Path Guide¶

Work type	Area path
Platform IaC, Ansible, k3s, pipelines, security, docs	`archon-platform\Platform`
Application code, CMMS, OpenClaw, Grafana dashboards	`archon-platform\Apps`
Cloudflare, Azure, Terraform	`archon-platform\Cloud`
ADO pipelines, CI/CD	`archon-platform\Pipelines`
OT firmware, MQTT, alarms (ALM-*)	`archon-platform\OT`
Default (when none of the above fit)	`archon-platform\Platform`

Never leave area at the root archon-platform. It routes the WI outside all team board filters.

Sprint Assignment Rule¶

Always look up the current active sprint dynamically. Do not hardcode sprint names.

CURRENT_SPRINT=$(az devops invoke \
  --area work --resource iterations \
  --route-parameters project=archon-platform team="archon-platform%20Team" \
  --api-version 7.1 --output json 2>/dev/null | \
  python3 -c "
import json, sys
for i in json.load(sys.stdin).get('value', []):
    if i.get('attributes', {}).get('timeFrame') == 'current':
        print(i['path']); break
")

This returns a path like archon-platform\Sprint 2. Use it directly with --iteration.

Mandatory WI Creation Pattern¶

az boards work-item create \
  --title "<title>" \
  --type Task \
  --project archon-platform \
  --area "archon-platform\Platform" \
  --iteration "$CURRENT_SPRINT" \
  --fields "System.Tags=<tag>"

ALM Alarm WI Handling Policy¶

Alarm WIs are auto-generated by alarm_bridge when OT alarms fire (ALM-REDACTED, ALM-REDACTED, etc.). They are not operator-actionable tasks and must not pollute the Platform sprint board.

Rules: - Area path: archon-platform\OT (permanently routes them off the Platform board) - Iteration: current active sprint (so they appear on the OT area board, not orphaned) - State: leave as-is (New) unless the alarm is being investigated - Do not reassign ALM WIs to operators unless the alarm triggers a formal incident

The alarm_bridge service must be updated to set these fields at creation time. See cmms_alarm_bridge config in archon-apps for the WI creation call.

Team Board Configuration¶

Current settings (set 2026-04-19):

Setting	Value	Notes
Team area filter	`archon-platform` with `includeChildren: true`	Shows all sub-areas on board
Default iteration	`@currentIteration` (Sprint 2 as of Apr 19)	Auto-advances each sprint
Backlog visibilities	Epics, Features, Stories	Tasks appear on sprint board only
Bugs behavior	`asTasks`	Bugs appear in sprint task rows

Note: ADO does not support TaskCategory as a backlog level in this process template. Tasks are visible on the sprint board (not the backlog board) once a sprint is assigned.

Board Visibility Check¶

Run at every session close (built into ccagnt-session-light Step 4 and ccagnt-session-full Step 9).

# WIs with no sprint (root iteration)
az boards query \
  --wiql "SELECT [System.Id],[System.Title],[System.AreaPath],[System.IterationPath] \
  FROM WorkItems WHERE [System.TeamProject]='archon-platform' \
  AND [System.IterationPath] = 'archon-platform' \
  AND [System.State] NOT IN ('Done','Closed','Resolved') ORDER BY [System.Id] DESC" \
  --output table

# WIs with root area path
az boards query \
  --wiql "SELECT [System.Id],[System.Title],[System.AreaPath],[System.IterationPath] \
  FROM WorkItems WHERE [System.TeamProject]='archon-platform' \
  AND [System.AreaPath] = 'archon-platform' \
  AND [System.State] NOT IN ('Done','Closed','Resolved') ORDER BY [System.Id] DESC" \
  --output table

Target state: both queries return zero rows. Any row is a violation that must be fixed before the session closes.

Correcting Existing Violations¶

# Assign sprint and area path to a single WI
az boards work-item update --id <id> \
  --iteration "$CURRENT_SPRINT" \
  --area "archon-platform\Platform"

# Batch fix -- for a list of IDs
for id in 249 248 247; do
  az boards work-item update --id $id \
    --iteration "$CURRENT_SPRINT" \
    --area "archon-platform\Platform" \
    --output none
done