sync

/audit:sync — Azure DevOps work-item sync

Mirrors the manifest's bugs[], tasks and (via phaseWorkItems) phases into Azure DevOps work items and back. No background magic: every invocation does exactly one direction, shows its plan, and is idempotent (re-running converges; nothing duplicates). The orchestrator additionally echoes already-linked items on status transitions (update-only — see orchestrator.md → "ADO echo"); this command is the reconciler that heals whatever the echo missed.

$ARGUMENTS: first token is the subcommand — connect, push, pull, parents or status. Unknown/empty → print usage and stop.

connect is the one that runs before meta.ado exists, so Preflight 2 below does not apply to it: it is how the block gets written. Every other subcommand still stops without one.

0. Preflight

1. Read ${CLAUDE_PLUGIN_ROOT}/reference/manifest-conventions.md and ${CLAUDE_PLUGIN_ROOT}/reference/tracker-sync.md (the shared contract + the ADO binding: field reference names, state fallback, parent links, iteration resolution). Resolve and read the manifest. Missing → stop, point to /audit:init.

   The manifest may be SHARDED, and then the file at manifestPath is an INDEX whose phases are stubs — the tasks, and every ado link on them, live in the phase shards beside it. A plain read of that file is therefore not a read of the manifest: it finds the bugs' links and none of the phases' or tasks', and reports the difference as unlinked rather than as unread. Nothing errors; the number is simply smaller. Every script below goes through _manifest_io.load_manifest, and the counts and links this command would otherwise walk itself come from read-ado-links.py (step 2 of status). No step in this file wants the raw file, so if you are about to Read the manifest to count something, that is the door to run instead.

2. meta.ado must exist — else stop and point at /audit:sync connect, which verifies the transport, reports which auth path is in effect, proves access with a read-only query and detects the board's process before writing the block. Print the snippet too, for anyone who would rather write it by hand:

   "ado": { "organization": "<org>", "project": "<project>",
            "areaPath": null, "iterationPath": null,
            "types": { "bug": "Bug", "task": "Task" } }
   

   (The v2 keys — stateMap, sprint, pull, onComplete, comments, echo, phaseWorkItems, enabled — are optional; the panel's ADO card edits them all.)

3. meta.ado.organization and meta.ado.project must BOTH be set once the connector is enabled. Both stay optional at the schema level — connect writes them together, but nothing refuses a hand-edited block that skips them — so an enabled connector missing either is a declaration with nowhere to push or pull: push/pull STOP with connector declared but not addressed — set meta.ado.organization and meta.ado.project (or run /audit:sync connect); status still runs and leads with the same note. This is the gap /audit:doctor reports as a finding, not a warning: the other two silences this preflight names (no meta.ado at all, step 2; enabled: false, step 4) are declared inactivity, while this one says the connector is ON and has nowhere to go — the quiet failure a maintained-looking board can hide.

4. meta.ado.enabled: false disables writes: push and pull STOP with connector disabled — re-enable in the panel's ADO card (or set meta.ado.enabled); status still runs (read-only is the drift lens you need to decide whether to re-enable) and leads with connector DISABLED — N linked item(s) frozen, links kept.

5. Transport: if mcp__azure-devops__wit_* / mcp__azure-devops__work MCP tools are available in this session, you MAY use them (same field mapping below). Otherwise use the az CLI via Bash: az devops configure --defaults organization=https://dev.azure.com/<org> project=<project> then az boards .... If az is missing or the azure-devops extension isn't installed, STOP with install guidance (az extension add --name azure-devops; auth via az login, or the AZURE_DEVOPS_EXT_PAT environment variable in CI).

6. Credentials are never yours to handle: never write a PAT/token into the manifest, the config, or any file; never echo one (the secret guard blocks it anyway). Auth belongs to az / the MCP server.

7. After EVERY manifest mutation: revalidate with python3 "${CLAUDE_PLUGIN_ROOT}/scripts/manifest/validate-manifest.py" <manifestPath>.

8. push/pull write the manifest — hold the concurrency lock (see conventions → Concurrency lock) around those writes; status is read-only and never locks.