A claim is a lease on a directive, not a promise.
A directive is a scoped unit of work. A claim is what a worker takes out on it: the right to do that work, filed at the moment work starts. Filing the claim is the precondition for starting, and it is first-writer-wins. A second worker that tries to claim the same directive gets an already-claimed error back and picks up something else.
The claim also declares the files the work is expected to touch. That declaration is what makes collisions visible: it is on record before any code exists, so the system can reason about two directives' scopes instead of two finished diffs.
Overlap is caught at dispatch.
Vinculum answers the concurrent-code problem the same way for every directive: catch the collision before two workers touch the same lines, not after. When a grunt is dispatched with a declared scope, the substrate compares that scope against every live claim already in force. An overlap is surfaced right there, at dispatch, prefix-aware down to path segments so a directory scope and a file scope collide correctly.
Today that signal is advisory. It goes to the orchestrator, which narrows the scope, sequences the work, or proceeds deliberately, and a file-level lease rides along as a second advisory layer while the grunt runs. It is not yet an automatic refusal. The architectural decision (#7759) and the design of record extending it (#7762) ratify that hard version, where a claim whose scope intersects a live claim is refused outright and correctness is checked at the build-and-test gate rather than at the merge. The direction is settled; the mechanism has not shipped.
Caught where the work is planned, not where the diffs land.
A typical merge-conflict workflow lets two developers edit the same file on separate branches and finds out about the collision only when someone tries to combine both sets of changes. By then each side has already written code against an assumption the other side invalidated, and someone has to read both diffs and decide which lines survive.
Vinculum moves that check to the start. A directive whose declared scope overlaps a live claim is flagged when the grunt is dispatched, before it writes a line, and the orchestrator resolves it by re-scoping or sequencing rather than reconciling divergent code later. The collision surfaces where the work is planned, not where the diffs land, which is the whole reason scope is declared up front.
The hard interlock, ratified and pending.
The advisory checks above are what runs today. The hard file-level interlock, refusing an overlapping claim outright, is decided but not yet built. It was ratified as an architectural call (#7759), and the design of record extending it locks the granularity at the file level and sets the rule for what counts as a collision (#7762). Both are ratified design of record with a status of pending: the direction is settled, the mechanism is not shipped.
| The ratified design | Status |
|---|---|
| claim_scope becomes a hard interlock enforced at file granularity, so workers run isolated over disjoint scopes | #7759 · ratified, not yet shipped |
| Granularity locked at the file level: an overlapping claim is refused outright, with correctness checked at the build-and-test gate instead of at the merge | #7762 · ratified, not yet shipped |
Common questions.
What happens if two workers try to claim the same file?
Two workers cannot both hold the same directive. Claims are first-writer-wins, so the second to claim gets an already-claimed error and moves on. When two different directives declare overlapping files, the overlap is detected at dispatch and surfaced to the orchestrator, which narrows or sequences the work before either worker starts; the file lease that rides along is advisory. Turning that overlap into an automatic hard refusal is ratified design of record (#7759, #7762) and is not yet shipped.
How is this different from a normal git merge conflict?
A merge conflict surfaces after two people have written divergent code against the same lines, once someone tries to combine both sets of changes. Vinculum surfaces the collision earlier: overlapping scopes are flagged at dispatch, and the orchestrator resolves them before either worker writes code. The check moves from after-the-fact reconciliation to before-the-fact decomposition.
What does "scope overlap is a decomposition smell" mean in practice?
It means a directive that needs a file another directive already claimed was not split correctly upstream. The fix is decomposing the work so the scopes stay disjoint, not building a runtime mechanism to merge two workers' changes to the same lines after both have made them (#7762). Overlap is a signal to re-scope, which is why the model treats it as a smell rather than something to reconcile later.