[Feature] Git-aware multi-agent/worktree coordination and merge-result validation

[ohjonathan]

Summary

Ontos v5.0.2 protects a write transaction with <workspace>/.ontos.lock. That is valuable inside one worktree, but it cannot coordinate:

• two worktrees for the same Git repository;
• two devices;
• agents validating independently clean branches whose combined merge result creates duplicate IDs, cycles, broken edges, or enum drift;
• concurrent regeneration of committed derived artifacts such as Ontos_Context_Map.md;
• instruction files that contain content owned by Ontos, another CLI, and the repository owner.

The missing abstraction is not a bigger local lock. It is a Git-aware protocol that separates authoritative source content, check/render work, generated-artifact ownership, and merge-result validation.

This issue is the coordination layer over the portable snapshots in #173 and stable findings in #174.

Responsibilities

Agents

• Work on branches/worktrees and bind each session to an activation receipt/base SHA.
• Default to read/check/render-plan operations.
• Do not rewrite shared generated artifacts unless holding explicit ownership.
• Hand back base and final commit/snapshot IDs.

CLI and MCP clients

• Expose the same receipts, finding IDs, validation rules, and ownership state.
• Offer non-mutating check/plan modes for every generated artifact.
• Fail clearly on stale-session or ownership preconditions.
• Never imply that a host-local lock is a distributed lock.

Ontos

• Validate the merge result, not only each branch independently.
• Coordinate same-device worktrees through the Git common directory.
• Make generated-artifact ownership explicit and machine-readable.
• Support an optional compare-and-swap writer-intent backend for cross-device coordination.
• Keep offline read/check workflows available.

Proposed capabilities

1. Same-device repository coordination

Discover the Git common directory and use a repo-scoped coordination lock in addition to existing worktree transaction locks for repo-scoped Ontos outputs.

2. Generated-artifact ownership

Declare source docs/config as authoritative. Add commands equivalent to:

• ontos generated check / ontos map --check
• ontos generated plan
• ontos generated refresh --owner-token ...

Normal agent worktrees should validate/render without writing. One declared integrator, release queue, or explicitly leased session refreshes committed artifacts after source conflicts are resolved.

3. Merge-result validation

Add ontos merge-check --base <sha> --head <sha> or accept a GitHub test-merge SHA. Report findings that exist only in the combined graph, including duplicate IDs, cycles, broken links, enum drift, and generated-artifact divergence.

4. Optional cross-device writer intent

For teams that need it, support an explicit Git-ref/CAS or pluggable coordination backend carrying owner/session, base snapshot/SHA, path globs, nonce, TTL, and renewal/release state.

A local flock must never be advertised as cross-device protection. Offline mode should report distributed lease state as unknown, not free.

5. Conflict policy

Do not install a silent ours/theirs merge driver for source docs or user-owned instruction content. Resolve source and unmanaged-content conflicts explicitly, then regenerate deterministic derived artifacts.

Acceptance criteria

• Two worktrees on one device cannot concurrently mutate repo-scoped Ontos outputs unnoticed.
• A non-owner can still activate, query, validate, and produce a deterministic render plan.
• Non-owner writes fail closed with stable machine-readable errors and exact conflicting paths.
• Merge-check catches a duplicate ID and a cycle introduced only by combining two individually valid branches.
• Deterministic regeneration from the merged tree yields identical bytes/digests across devices.
• AGENTS.md unmanaged or other-tool-managed content is preserved; unresolved conflicts require explicit action.
• CLI and MCP report repo identity, worktree identity, snapshot/base SHA, ownership/lease state, and generated-artifact status consistently.
• Optional leases use compare-and-swap and cover expiry, renewal, release, and race tests.
• A stale agent receipt/base precondition is detected before any Ontos write.
• CI can validate a test-merge commit without mutating the checkout.

Non-goals

• Locking arbitrary product-code edits
• General project management or task assignment
• Requiring a Git hosting provider for core read/check operations
• Auto-pushing, auto-merging, or auto-resolving source conflicts
• Claiming distributed leases prevent malicious writers
• Treating committed generated files as more authoritative than their source graph

Related work

• [Feature] Content-addressed activation receipts and portable AGENTS/map freshness #173 — content-addressed activation receipts and portable freshness
• [Feature] Stable finding IDs, Git diffing, and no-new-debt validation baselines #174 — stable finding IDs and no-new-debt validation
• [P1] MCP dispatch unification & rename lock/rollback hardening (audit) #153 — local rename locking/rollback (necessary but narrower)
• [P1-containing] v5.0.1 patch-safe sweep + v6.0.0 path compatibility removal #149 — generated-artifact churn policy tail
• Machine-readable audit registry and external parity gate #165 — audit registry/parity, distinct from repository coordination