# ADR 007: Central coordination boundary for authoritative work

- HTML version: https://robbiepalmer.me/projects/work-graph/adrs/007-authoritative-work-graph
- Project: Work Graph (https://robbiepalmer.me/projects/work-graph.md)
- Status: Accepted
- Date: 2026-09-19
- Supersedes: work-graph:007-shortcut
- Initiatives: Semi-autonomous Software Development (https://robbiepalmer.me/initiatives/semi-autonomous-software-development.md)

## Context

[PDR 003](/projects/work-graph/pdrs/003-make-work-graph-authoritative) makes Work
Graph authoritative for migrated personal executable work. The architecture
must span initiatives, projects, repositories, and worker environments while
keeping project prose in the public knowledge graph.

The domain decisions already cover flexible work items, contextual priority,
dependency-derived readiness, fenced leases, and explicit terminal states. The
remaining choice is where those operations meet and how other systems interact
with that authority.

Repository-local agent trackers can coordinate one checkout well. They require
replication or another policy layer to order work and preserve evidence across
the whole initiative. Conventional trackers expose useful interfaces but do
not enforce Work Graph's leases, graph invariants, or evidence policy.

## Decision

Use one central Work Graph service as the application boundary for executable
work across the initiative. Keep current work state, graph relationships,
priority inputs, leases, evidence, and attention records behind that boundary.
Use stable knowledge-scope identifiers and source revisions to mirror projects
and initiatives without copying their narrative ownership.

Expose the complete operator workflow through the installed CLI and the REST
API from
[ADR 003](/projects/work-graph/adrs/003-rest-api-and-cli-first). The interface
must support capture, inspection, reprioritisation, and a deterministic
critical-path projection. The projection returns blocking paths, ready leaves,
independent branches, and blocking attention without estimating delivery
dates.

Integrate source control, CI, deployment platforms, infrastructure, and
observability as directional inputs. They may append observations, update
projections, or write through an authorised Work Graph operation. They cannot
own a parallel lifecycle or priority value. Any editable external projection
must commit through the central service before it reports success.

Keep importers and reconciliation paths for Shortcut, GitHub Issues, and
repository-local formats. Preserve external identities and source revisions so
imports can be audited without treating the source as a second live authority.

This central boundary supersedes the inherited Shortcut architecture for
migrated scopes. The owner accepted it on 25 October 2026 after the pilot and
cutover evidence recorded by PDR 003 passed.

## Consequences

All workers observe the same claims, graph edits, and priority projection.
Cross-project scheduling no longer depends on repository replication or a
client reconstructing global state.

The central service becomes an availability and recovery dependency. Database
backups, migration discipline, API compatibility, and CLI installation now
belong to the operated system.

Every integration needs an explicit direction and reconciliation rule. A
projection that accepts offline writes without a write-through contract would
reintroduce split-brain work state.

The CLI can support work from mobile or remote sessions through an agent
without a separate graphical client. A later graphical interface remains a
client of the same boundary.

## Alternatives considered

### Extend Shortcut with a coordination service

Shortcut could remain the visible tracker while a separate service handled
leases, evidence, and graph policy. Both systems would then participate in one
work item's lifecycle, and every state change would need conflict resolution.

### Use Beads as the repository-local authority

Beads provides dependency-aware work and leases with an offline-first Dolt
model. The initiative still needs central ordering, policy, and observations
across repositories. Adding those above Beads leaves two storage and sync
models for the defining coordination path.

### Store work in repository files

Repository state is easy to audit and works well for local plans. Atomic claims
across machines, cross-repository dependencies, and current global priority
would require a separate server or a conflict-prone merge protocol.

## Migration note

The 1 November 2026 PDR migration moved the authority, supported workflow, and
acceptance evidence into PDR 003. This ADR keeps the central service, CLI,
integration direction, and reconciliation architecture. The migration does not
change the 25 October acceptance or the Shortcut cutover.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt