Skip to content

ARC-ADR-056 — Integrated VFS and Board Coordination

One line: Unifying source code versioning (HVFS) and task tracking (Sharded Board) into an atomic, branch-scoped transaction boundary controlled dynamically by feature flags.

Context and Problem Statement

Traditionally, source code changes (Git) and task board transitions (Jira/GitHub Projects) are administrative silos. This separation leads to metadata drift: - Code is merged while the corresponding issue remains open (or vice versa). - Agents commit modifications to repositories without checking if the linked task card is blocked. - Humans lack real-time visibility into which files are actively being touched by which running swarm tasks.

We want to bind code changes and task movements into a single, atomic transactional workspace context, but we must do so incrementally using a feature flag toggle, so that either system can run independently in fallback mode.

Decision Drivers

  • Zero-Drift Invariant: The status of a task and its representing code branch must always be in sync.
  • Safety Gating: Code merges must be blocked if the corresponding task card has open blockers or unresolved decisions.
  • Rollback Consistency: Commit operations must be all-or-nothing; code metadata commits must fail if task status updates violate graph SHACL shapes.
  • Dynamic Adaptability: The integration must be easily enabled or disabled across specific organization sub-nets without redeploying code.

Considered Options

Option A — Decoupled Polling (Sync Daemon)

Keep the Virtual Filesystem and the Sharded Board database completely separate. Run an asynchronous background sync worker that polls branch commit messages (e.g. searching for "closes #302" patterns) and updates board states subsequently. - Pros: - Complete decoupling of VFS and Board systems. - Failures in the board system do not block code commits. - Cons: - High synchronization drift (eventually consistent, not atomic). - No capability for mutual locking (cannot prevent write collisions before they hit the codebase). - High polling API latency.

Option B — Fully Coupled Hard-Coded Integration

Directly hard-code board synchronization logic into the VFS client core. Checking out or committing files always writes to the task board database. - Pros: - Simple client-side architecture (no feature flag routing). - Cons: - Zero modularity: prevents running the virtual filesystem as a standalone Git replacement. - If the database board service is offline, all filesystem checkouts and commits fail.

Option C — Integrated VFS/Board Coordination with Feature Flag Gating (Chosen)

Establish the integration loop inside the VFS client, but gate all cross-cutting triggers behind the HVFS_HOLONIC_SYNC feature flag. Evaluated at startup, the client dynamically routes between atomic multi-mode execution (VFS + Board) and standalone fallback mode. - Pros: - Atomic Commits: Combines staged file blobs and card transitions into a single database transaction. - Mutual Locking: Lock commands (ut vfs lock) propagate instantly to both files and board cards. - Dynamic Fallout Resilience: If the board service is degraded, operators toggle the feature flag off to resume normal code-only git replacement operations. - Cons: - Adds evaluation and path routing complexity inside the VFS client library.

Decision

Adopt Option C. Integrate the virtual filesystem client and the sharded board system, gating the integrated loop behind the HVFS_HOLONIC_SYNC feature flag.

1. Atomic Commit Flow

With the HVFS_HOLONIC_SYNC flag enabled, ut vfs commit compiles both local file mutations (.vfs_staging.db) and local board status transitions (.vfs_board.db) into a unified JSON transaction payload:

{
  "repository": "middle-core",
  "branch": "task-wi-305",
  "commit_metadata": { "message": "feat: wire events", "author": "csharp-developer" },
  "file_mutations": [ { "path": "Events.cs", "action": "modified", "content_hash": "a45c095906..." } ],
  "board_mutations": [ { "holon_id": "wi-305", "action": "status_change", "new_status": "review" } ]
}

The UDA processes the commit as a single ArcadeDB transaction. If either the file indexing fails or the board transition violates SHACL shapes, the entire transaction rolls back.

2. Mutual Lock Propagation

  • File-to-Board Lock: When an agent locks a path via ut vfs lock app/api/, the corresponding Story node on the master board is automatically marked Locked, blocking sibling updates.
  • Board-to-File Lock: If a human moves a Feature card to "Locked/Audit" on the cockpit UI, sibling VFS clients dynamically pull the state and block write operations to all code files mapped to that Feature.

Consequences

  • + Zero Administrative Drift: Backlogs and codebases are atomically synced.
  • + Safety Gated Merges: Code cannot be merged if linked tasks have open blockers.
  • + Incremental Rollout: Feature flag gating allows testing in sandbox environments before organization-wide enablement.
  • − Evaluation Overhead: Requires evaluating feature flags on startup (mitigated by local flag caching).
  • − Lock Contention: Broad path locks can block parallel development if not scoped narrowly.

Alternatives Considered

  • Decoupled Polling (Option A): Rejected due to the risk of code merging while tasks remain open, violating zero-drift invariants.