v3/docs/adr/ADR-327-federated-concurrent-development-harness.md
Status: Proposed — generator guidance and in-memory conformance references implemented; distributed enforcement pending
Date: 2026-07-28
Decision owners: Ruflo Codex, claims, policy, and developer-experience maintainers
Related: ADR-320, ADR-324, ADR-325, ADR-326
Ruflo will support repository-local development harnesses as adapters into its policy-governed concurrent workflow.
The useful primitives observed in the cognitum.one website harness are adopted:
Those primitives are coordination evidence, not authorization. They supplement but never replace Ruflo's stronger invariant that every writing agent uses a distinct Git worktree.
Ruflo will define one versioned harness contract with:
Generator and AGENTS guidance will teach Codex to discover and join a tracked repository harness without weakening the worktree or policy rules. Distributed lease enforcement remains proposed until the acceptance tests pass.
The Codex package now includes source/build evidence capture plus
InMemoryFencedLeaseReference, InMemoryInboxReference, and
InMemoryRunReceiptReference. These are deliberately unsigned, non-persistent,
single-process conformance/debug references:
observe and advisory;They do not implement a CP lease service, durable inbox/outbox, signed hash-chained ledger, restart recovery, or release-decision composer. An external-authority adapter satisfying the normative sections below remains required for enforcement and release.
The cognitum.one website harness currently provides a practical, file-backed coordination layer:
This is useful local coordination, but the live audit found:
HEAD cannot identify which dirty source state
was tested;The harness correctly treats a missing PID as insufficient proof of death. Lease expiry and heartbeat are the right liveness abstraction, but production concurrency requires fencing and exact source-state receipts.
HEAD alone is not an exact source-state identity when a worktree is dirty.Ruflo discovers a harness only through tracked repository configuration:
interface RepositoryHarnessAdapter {
describe(): Promise<HarnessDescriptor>;
start(request: StartSessionRequest): Promise<HarnessSession>;
acquire(request: LeaseRequest): Promise<FencedLease>;
renew(lease: FencedLease): Promise<FencedLease>;
release(lease: FencedLease): Promise<void>;
send(message: HarnessMessage): Promise<MessageReceipt>;
receive(cursor?: string): AsyncIterable<HarnessMessage>;
acknowledge(messageId: string): Promise<void>;
recordRun(run: RunEvidence): Promise<RunReceipt>;
authorizeRelease(request: ReleaseRequest): Promise<ReleaseDecision>;
end(sessionId: string): Promise<void>;
}
Repository scripts remain the preferred local user interface. Ruflo does not replace a project's custom harness or invent commands. The adapter reads its declared capabilities and invokes only supported operations.
If no tracked harness exists, Ruflo uses its local claims and policy providers. If an explicitly selected harness is unavailable, protected operations fail closed.
The parent agent creates or assigns a distinct worktree before a writing worker acquires paths. A lease then provides fine-grained ownership inside that worktree and across agents:
isolated worktree
+ non-overlapping path/resource lease
+ narrow authorization capability
+ current fencing token
= eligible protected write
Read-only agents may share a checkout if they acquire no writing lease. One designated integration agent owns shared manifests and lockfiles.
Legacy shared-worktree harnesses remain observable in compatibility mode, but Ruflo does not describe them as isolated or receipt-complete. Their dirty source state cannot authorize release.
A repository identity binds at least:
interface RepositoryIdentity {
repositoryId: string;
canonicalRemote?: string;
gitCommonDirId: string;
rootTreeId: string;
}
Paths are repository-relative, Unicode-normalized, separator-normalized, free
of . and .., checked after symlink resolution, and compared with the
platform's case behavior. Option-like values are rejected.
The preferred source state is a clean, committed worktree:
SourceStateID = sha256(repositoryId || commit || tree)
When a local test intentionally covers uncommitted work, the receipt also binds:
Such a local receipt may support debugging. A release receipt still requires a clean committed state unless a project policy explicitly defines an equally strong immutable snapshot mechanism.
The lease authority performs compare-and-swap transactions:
interface FencedLease {
leaseId: string;
repositoryId: string;
sessionId: string;
ownerWorkloadId: string;
worktreeId: string;
kind: 'path' | 'resource';
scopes: string[];
epoch: bigint;
version: bigint;
issuedAt: string;
expiresAt: string;
}
Acquire, renew, release, and steal validate the expected version and current
owner. Every successful new ownership period increments epoch, including
reacquisition by the same session.
Filesystem adapters provide single-host compatibility. Distributed workflows use a linearizable authority. Protected integrations, deployment drivers, and shared generators compare the presented epoch with the authority before a side effect. An old holder cannot continue merely because it still has local files.
Heartbeat proves current lease intent; PID is diagnostic only. A long-running operation uses bounded renewable leases and cannot declare a mutex stale solely because a fixed wall-clock duration elapsed.
A lease answers, "which worker currently owns this coordination scope?" A grant answers, "may this identity perform this action?"
The ADR-324/325 decision request includes both:
subject and workload identity
repository and source state
action and exact resource
lease ID, scope, epoch, and expiry
authorization grant
budget/concurrency/delegation envelope
policy version
No lease, session, message, test result, or agent role can synthesize a deployment, network, spend, secret, administrative, or product capability.
Harness messages use stable IDs, issuer and audience, correlation and causation IDs, sequence, expiry, content digest, and acknowledgement state.
Delivery is at least once. The receiver deduplicates by issuer, message ID, and content digest. A repeated ID with different content is quarantined. A bounded UI view may show the most recent messages, but durable storage retains unacknowledged handoffs and supports cursor resume.
Messages communicate observations, requests, conflicts, and handoffs. They do not transfer path ownership or authority unless the corresponding lease or grant transaction separately succeeds.
A run receipt includes:
interface HarnessRunReceipt {
receiptId: string;
repositoryId: string;
sourceStateId: string;
sessionId: string;
workloadId: string;
commandDigest: string;
scope: string;
profile: 'focused' | 'integration' | 'release';
startedAt: string;
completedAt: string;
exitCode: number;
evidenceDigest: string;
policyReceiptId: string;
leaseEpochs: Record<string, string>;
}
Receipts are recursively canonicalized, content-addressed, signed, and append-only. Retrying a command creates another execution ID; it does not rewrite history.
A release decision requires:
Deploy remains dry-run unless the user and policy authorize execution. A passing run receipt is evidence, not deployment authority.
Cross-repository work uses explicit producer and receiver ownership:
producer commit and evidence
-> signed handoff referencing exact source state
-> receiver acknowledges
-> receiver acquires its own local paths and capability
-> receiver implements and verifies its side
One agent does not write into another dirty repository merely because both participate in the same swarm. Contract changes identify the receiving owner, compatibility window, and validation evidence.
This is especially important for Cognitum website to Meta-LLM structured output, Cog release provenance, Comms event delivery, and RuView edge contracts.
Generated AGENTS guidance follows ADR-329's complete implementation loop: recall, inspect, route, plan, execute, test, validate, benchmark, optimize, receipt, handoff, and independently authorized publish. Harness-specific actions occur inside that loop:
Ruflo coordinates this flow. Codex still performs the implementation and verification work.
observe adapter that imports session, lease, message,
port, and run evidence without authorizing privileged actions.0 and are advisory. They cannot
authorize release.enforce only after writers use isolated worktrees,
protected resources validate fencing tokens, and exact-source receipts pass.HEAD produce different
source-state identities.HEAD.Review this ADR when Git changes its worktree identity model, a repository harness adds distributed leases, Ruflo supports a new source-control system, or production evidence demonstrates a different lease or receipt requirement.