RFC-0010: Multi-workspace coordination for parallel agents

Version: 0.2.0 | Status: normative | Phase: impl Owners: @govctl-org Tags: collaboration

References: RFC-0004, RFC-0002

1. Summary

[RFC-0010:C-SUMMARY] Summary (Informative)

This RFC specifies how govctl coordinates governance work when one repository clone hosts multiple concurrent working trees — git worktrees or jj workspaces — driven by parallel agents.

Scope: Applies to every govctl command invocation in any working tree of a clone that hosts more than one working tree. It covers command scope classification, a shared coordination registry, cross-workspace ID reservation, exclusive claims for version-semantics operations, and cross-workspace presence visibility.

Backward compatibility: Single-checkout repositories are unaffected: with exactly one working tree, coordination reduces to the behavior defined by RFC-0004. Without version control, multiple workspaces cannot exist, so commands silently behave as they always have. One deliberate exception: because allocation consults shared version-control history, identifiers of deleted artifacts are not reused, which protects historical references from dangling onto unrelated successors.

Specification outline: Commands are classified as workspace, branch-content, or trunk scoped, and trunk-scoped commands are refused outside the primary workspace. A per-clone coordination registry holds ID reservations, artifact claims, and presence records. ID reservation makes cross-branch ID collisions impossible by construction; claims make concurrent version-semantics changes to the same RFC visible and serialized; presence lets agents in one workspace see active work in others.

Rationale: Governance artifacts remain versioned with the branch so that changes travel through pull request review, while coordination state — which is live, operational, and not reviewable — is shared per clone. Without this split, parallel agents in separate worktrees collide on sequential IDs, cannot see each other’s active work, and can silently bump or finalize the same RFC.

Since: v0.1.0

2. Specification

[RFC-0010:C-DEFINITIONS] Definitions (Informative)

Working tree / workspace: A distinct checkout of a repository clone that shares version-control metadata with the clone’s other working trees — a linked git worktree or a jj workspace. A workspace is identified by the absolute path of its working-tree root. Moving or renaming a workspace therefore invalidates its registry records, which expire under the liveness rules below and are recreated by new activity from the moved workspace.

Primary workspace: The working tree designated as the canonical location for trunk-scoped commands. For git, the main working tree (the one containing the repository’s shared metadata directory). For VCS tools whose workspaces are peers, the workspace named by project configuration.

Shared repository storage: Storage provided by the version-control system that is common to every working tree of a clone, such as the git common directory or the jj repository store. It is distinct from any working tree’s checked-out files. Shared version-control history is the commit history recorded in that shared storage and visible to every workspace of the clone.

Coordination registry: Local, per-clone state in shared repository storage that records ID reservations, artifact claims, and presence records. The registry is coordination state, not a governed artifact, and is never committed to version control.

ID reservation: An atomic registry record that binds a not-yet-merged artifact ID to the workspace that generated it. Reservation liveness is defined by RFC-0010:C-ID-RESERVATION through the existence of the artifact file at the owning workspace’s recorded path, not by an activity timestamp.

Artifact claim: An exclusive registry record binding an existing RFC to the workspace performing version-semantics operations on it.

Presence record: A registry record indicating that a workspace is actively working on a specific work item.

Live record: A claim or presence record whose owning workspace path still exists and whose recorded activity has not exceeded the configured inactivity period.

Since: v0.1.0

[RFC-0010:C-COMMAND-SCOPE] Command scope classification (Normative)

Every govctl command that reads or writes governed artifacts or coordination state has exactly one scope: workspace, branch-content, or trunk. This classification applies to every command in the CLI surface defined by RFC-0002, and any command added to that surface MUST be assigned exactly one scope at the time it is added.

Workspace scope. Read-only and local-execution commands such as status, check, list, show, search, verify, describe, claim list, and loop execution. Workspace-scoped commands MUST run in any workspace and MUST NOT mutate governed artifacts. Coordination-state-mutating commands that never touch governed artifacts, such as claim release and claim steal, are branch-content scoped for enforcement purposes but MUST NOT acquire the gov-root write lock.

Branch-content scope. Commands that create or mutate governed artifacts in the invoking workspace’s working tree, including artifact creation, content editing, lifecycle transitions, and rendering. Branch-content commands MUST run in any workspace, subject to the reservation and claim rules of RFC-0010:C-ID-RESERVATION and RFC-0010:C-ARTIFACT-CLAIM.

Trunk scope. Exactly the commands that cut or undo a release or migrate the repository’s governance format are trunk-scoped. A trunk-scoped command invoked outside the primary workspace MUST refuse to execute, MUST leave governed and coordination state unchanged, and MUST report a diagnostic that identifies the primary workspace.

The primary workspace MUST be determined from version-control metadata when the VCS defines a main working tree. Where the VCS treats workspaces as peers, the primary is the workspace named by project configuration, or — absent configuration, for jj — the workspace named default, which jj assigns to the initial workspace of every repository. When version control is present but no primary workspace can be determined, trunk-scoped commands MUST proceed as if the current workspace were primary and MUST emit a warning that trunk-scope enforcement is inactive. Without version control, multiple workspaces cannot exist, so trunk-scope enforcement is inapplicable and commands proceed silently, consistent with RFC-0010:C-REGISTRY degradation.

Rationale: Release cutting, release undo, and format migration rewrite the canonical line of project history and must have a single point of execution, while content work benefits from running wherever the agent’s branch lives. Refusing trunk operations in secondary workspaces replaces an entire class of merge conflicts with an explicit, actionable error. The warning is reserved for the case where enforcement is expected but impossible; a project without version control has no second workspace to protect against. Treating jj’s initial default workspace as the fallback primary mirrors the convention every jj repository already has, so most projects need no configuration at all.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-REGISTRY] Shared coordination registry (Normative)

The coordination registry MUST be stored in shared repository storage so that every workspace of a clone observes and updates the same records. The registry MUST be namespaced per governed project root, so a clone hosting multiple governed projects keeps independent registries.

The registry MUST NOT be stored inside any workspace’s working tree, under the gov root, or under rendered documentation directories. Registry records are local coordination state: they are not governed artifacts, MUST NOT be committed to version control, and MUST NOT be treated as an authoritative source over TOML governance artifacts. The registry MAY inform only coordination-facing output — the presence overlay in govctl status and reservation or claim diagnostics — and MUST NOT alter the parsed content, status fields, or lifecycle state of governed artifacts as loaded from their TOML sources.

Concurrent registry updates from parallel processes across workspaces MUST be atomic: two concurrent invocations MUST NOT produce lost, duplicated, or interleaved registry records. This coordination mechanism is distinct from, and does not replace, the concurrency mechanism required by RFC-0004 for mutations of the gov tree. Registry access MUST NOT block read-only commands.

Because multiple working trees are themselves a version-control facility, a directory without version control cannot host more than one workspace. Commands in such a directory MUST silently use single-checkout behavior; coordination is not merely inactive but inapplicable, and no warning is emitted. Degraded detection MUST resolve toward caution: when version-control metadata is present but unreadable, or its presence cannot be reliably determined, commands MUST behave as if version control were present and shared storage were unavailable — that is, degrade with a warning — rather than taking the silent no-VCS path. Under the same caution rule, a registry write failure or detected registry corruption with version control present MUST degrade to single-checkout behavior and MUST emit a warning, since the clone may host other workspaces whose coordination state is now stale. Registry loss or corruption MUST NOT make governed artifacts unusable; the consequence is limited to losing the uniqueness and visibility guarantees of this RFC until the registry is repopulated by new activity.

Rationale: Placing coordination state in VCS-shared storage gives every workspace of a clone a single rendezvous point without a daemon or network service, while keeping the working tree — and therefore pull requests — free of operational state. Because the storage is VCS metadata rather than a checked-out file, the registry requires no ignore rules. Warning on registry failure when version control is present surfaces a real coordination gap, while staying silent without version control avoids punishing single-checkout projects for a facility they cannot use.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-ID-RESERVATION] Cross-workspace ID reservation (Normative)

A branch-content command that creates a governed artifact with a generated identifier MUST atomically reserve that identifier in the coordination registry as part of creation, and the reservation MUST record the owning workspace.

Two artifact creations in different workspaces of the same clone MUST NOT be assigned the same identifier, regardless of when their respective branches merge. This extends the concurrent-invocation uniqueness required by RFC-0004:C-CONCURRENT-WRITE from same-checkout processes to across-workspace sequences. Across clones — where no shared registry exists — identifier strategies that derive collision-safe identifiers from author identity or randomness remain the available mitigation.

Identifier allocation MUST take as its input the union of three witnesses: the identifiers present in the invoking workspace’s gov tree, the identifiers bound by live reservations in the registry, and the identifiers recorded in the clone’s shared version-control history. An identifier is recorded in shared history when a governed-artifact source path bearing that identifier exists in any commit reachable from the clone’s shared storage. Allocation MUST choose the next identifier monotonically within the numbering scheme of the artifact type, so identifiers stay sortable and predictable for humans. Because shared history is visible to every workspace of the clone, a merged artifact witnesses its identifier even to workspaces on stale branches.

A reservation for a newly created artifact MUST be honored as live while the artifact file exists at the owning workspace’s recorded path. The reservation MAY be discarded only once the artifact is recorded in the clone’s shared version-control history, from which point the history entry is the uniqueness witness for every workspace.

Rationale: Sequential identifiers are a deliberate readability choice for RFCs and ADRs. Reservation preserves that choice under parallel branch work by moving the collision point from merge time — where renumbering breaks references — to creation time, where an atomic shared record costs nothing. Defining the allocation input as local tree plus reservations plus shared history keeps the uniqueness guarantee intact across the reservation’s entire lifecycle, including after its discard.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-ARTIFACT-CLAIM] Artifact claims for version-semantics operations (Normative)

Operations that change an RFC’s version semantics — version bump, finalization, phase advancement, deprecation, and supersession — MUST acquire an exclusive artifact claim before mutating, on every RFC whose version-semantics fields the operation mutates. A supersession therefore requires claims on both the superseding and the superseded RFC. When another workspace holds a live claim on a required RFC, the command MUST fail without mutating anything, and its diagnostic MUST identify the claiming workspace.

Commands that edit an RFC’s content without changing version semantics — including clause authoring — MUST NOT be blocked by a claim. When a live claim held by another workspace exists, they MUST emit a non-blocking warning naming the claiming workspace, so overlapping intent is visible without forbidding parallel work on independent clauses.

A claim MUST record the owning workspace and a last-activity timestamp. Any govctl invocation that writes coordination state in the claiming workspace SHOULD refresh that workspace’s claim and presence timestamps; read-only invocations MUST NOT refresh, so that they never become writers. A claim whose owning workspace no longer exists, or whose last activity exceeds a configurable inactivity period, MUST be treated as expired and MUST NOT block operations.

Users MUST be able to explicitly release a claim and to take over a claim held by another workspace. Every takeover MUST be recorded in the registry as an audit event that names both workspaces involved, and audit events MUST be retained beyond the expiry of the claim they transferred, so that claim transfers remain auditable after the fact.

Rationale: Version-semantics operations on one RFC cannot merge meaningfully when performed on two branches at once — both would edit the same version and changelog fields — so they are serialized by an exclusive claim. Content edits to independent clause files merge cleanly, so they receive visibility rather than exclusion. Refresh is scoped to coordination-writing invocations so that read-only commands never take the registry lock, per RFC-0010:C-REGISTRY.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-PRESENCE] Cross-workspace presence (Normative)

Activating a work item — or creating one directly in active status — in any workspace MUST register a presence record in the coordination registry naming the work item and the owning workspace.

govctl status MUST surface work items with live presence records owned by other workspaces of the clone, identifying both the work item and the owning workspace, so an agent can tell which items are being worked on elsewhere before starting new work.

Presence records follow the liveness rules of RFC-0010:C-ARTIFACT-CLAIM: they record a last-activity timestamp, are refreshed by invocations in the owning workspace, and expire after the same configurable inactivity period.

Presence is advisory visibility, not exclusion: it MUST NOT block activating or editing the same work item in another workspace. Where hard coordination for work items is wanted, projects use work item dependency and assignment workflows rather than presence.

Rationale: The common multi-agent failure is two agents unknowingly doing the same work. A live, shared view of active work removes the invisibility without turning advisory information into a locking protocol.

Tags: collaboration

Since: v0.1.0

Changelog

v0.2.0 (2026-09-08)

Clarify trunk scope and workspace detection

Added

• Name release undo in the trunk-scoped command set
• Classify claim list as workspace-scoped and claim release/steal as lock-free branch-content commands
• Treat jj’s default workspace as the fallback primary when no primary is configured

Changed

• Scope claim and presence timestamp refresh to coordination-writing invocations so read-only commands never write

v0.1.0 (2026-09-08)

Initial normative version