Skip to content

Git designed for AI agents.

doc: PLAN10 15, gitai's resolver design, with the composition check measured

Federico Elia24558af334d0
diff --git a/doc/graft/PLAN10.md b/doc/graft/PLAN10.md
index 8856708..4f3164b 100644
--- a/doc/graft/PLAN10.md
+++ b/doc/graft/PLAN10.md
@@ -816,3 +816,213 @@ flag.
* An AI-landed merge is signed Graft-Resolved-By: llm/<model> and Graft-Checked-By:
syntax,composition, and the trace records the proposal and the report.
* Everything above still applies: a resolution that fails a check is a proposal.
+
+## 15. gitai's resolver design
+
+**Principle.** A conflict is two changes to one base. Only the server holds the base, both
+histories, the landing commit and the agent's request, so the server is the place to check what
+it can check mechanically, and the agent, who decides, gets a proposal with an honest report of
+what was checked, not a bare guess.
+
+The four diagrams below are the source of truth of the flow. A code path that is in no diagram is a
+patch and is removed; a commit that changes the flow changes the diagrams in the same commit, and
+the reviewer checks the code against them with the table that follows. (planned) marks what does
+not exist yet; (not enabled) marks what is designed and measured but switched off.
+
+### 15.1 End to end
+
+```
+ agent: UserLand(branch, commit[, resolve_conflicts | resolution])
+ |
+ |-- resolution given? --yes--> PRECHECK, before the lane, in a discarded quarantine
+ | branch moved / change already landed -> skipped (lane answers)
+ | review: exact paths, modes, markers, pointer lines, size
+ | resolver check (syntax + operator checks), bounded slots
+ | |
+ v v
+ LANE (one per branch) ---------- landWithResolution: tip moved -> refuse, fresh PACKAGE
+ | applies the precheck's verdicts; any failure -> PACKAGE
+ | operator verify.command on the merged tree; fails -> PACKAGE
+ | all good -> LAND as agent/<actor> (+ Graft-Checked-By)
+ v
+ 3-way merge of tip and commit
+ |-- clean -------------------------------------------------------------> LAND
+ |-- conflicts, no resolve_conflicts ------------------------------------> merge_conflict
+ |-- conflicts, resolve_conflicts
+ |
+ v
+ list the conflicting files (bounded) -> one VERDICT per file (15.2)
+ |
+ v
+ decide: LAND only if every file is resolved by an operator rule (15.4)
+ |-- yes -> operator verify.command; passes -> merge commit signed by the rules -> LAND
+ | fails -> PACKAGE (every file REJECTED, reason)
+ |-- no -> PACKAGE to the agent (merge_conflict detail): sides by OID, hunks,
+ per-file outcome + reason, per-file proposal (+ its report, planned),
+ the proposals kept under refs/graft/proposals/ (14)
+ |
+ v
+ the agent resolves (takes, edits or replaces the proposals) and
+ re-lands with resolution (top of this diagram)
+```
+
+### 15.2 Per file
+
+```
+ conflicting file
+ |
+ v
+ classify: path policy, shape, size, binary, lockfile, generated, minified
+ |-- not sendable ----------------------------------------> AGENT (NOT_SENT, reason)
+ v
+ operator rules in their order (trivial, union, rerere, command), each with the syntax check and
+ the operator's checks
+ |-- a rule resolved it ---------------------------------> VERDICT RULE (lands, 15.4)
+ v
+ AI configured? --no-------------------------------------> AGENT (FAILED: no strategy applied)
+ | yes
+ v
+ split into regions (3-way line diff); regions only one side changed are merged locally
+ |-- more than max_regions (20) ------------------------> AGENT (NOT_SENT: regions)
+ v
+ for each region, one call: PATCH = base->theirs (3 context lines), CODE = ours (3 anchors),
+ THEIRS' commit message; per-region checks: last answer block, anchors, newline rule, not a
+ patch, size, markers
+ |-- any region fails -------------------------------------> AGENT (REJECTED, reason; no proposal:
+ | all or nothing)
+ v
+ assemble the file; file checks: markers, tree-sitter syntax, operator checks
+ |-- a check fails ----------------------------------------> AGENT (REJECTED, reason)
+ v
+ composition report (15.3) (planned)
+ v
+ VERDICT PROPOSAL (PROPOSED, the proposal + its report)
+ [AI landing when every deterministic check passes: designed by Federico's amendment (14),
+ NOT ENABLED: the measurement in 15.5 shows no deterministic check that reaches the bar]
+```
+
+### 15.3 Composition report (planned; a report, not a gate)
+
+```
+ base B, ours O, theirs T, result R (normalized lines)
+ |
+ v
+ diff3 regions of (B, O, T); does R keep every clean segment, in order?
+ |-- no --------------------------------------------------> "changes lines outside the conflicts"
+ v
+ each region's slot in R; each side's hunks of base->side inside the region
+ |
+ v
+ hunk the other side did not touch (uncontested):
+ its added lines in the slot, its deleted lines gone --> "keeps <side>'s change at a-b"
+ otherwise -------------------------------------------> "drops <side>'s change at base a-b"
+ hunk whose base lines the other side also edited (contested):
+ --------------------------------------------------------> "contested region resolved freely"
+ (nothing line-level to verify)
+ a line both sides added, repeated more than either has it -> "duplicates a line both sides added"
+ a line in none of B, O, T --------------------------------> "content in neither side" (warning)
+```
+
+### 15.4 The one decision point
+
+```
+ decide (today: resolveLandConflicts, with landAnswerProposes; one function, planned: decideLand)
+ every file resolved by an operator rule ...... LAND (then verify.command)
+ anything else, including any model answer .... PACKAGE (the model's files are proposals)
+ No other code path lands a model's resolution. No check disables itself: a configuration that
+ cannot be used stops the server at startup, and a failure at run time refuses the land. No
+ confidence that the model declares about itself decides anything.
+```
+
+### 15.5 Box to code (the reviewer's audit table)
+
+| diagram box | function | file |
+|---|---|---|
+| UserLand, PRECHECK | `UserLand`, `landPrecheckInQuarantine`, `landPrecheckResolution` | operations/land.go, land_reland.go |
+| review of a resolution | `landReviewResolution`, `resolver.ValidateFile(WithSides)`, `landModeOfSides` | operations/land_reland.go, land_resolve.go; graft/resolver/validate.go |
+| resolver check, bounded slots | `landCheckResolution`, `landCheckSlotted`, `Client.AcquireCheckSlot` | operations/land_reland.go; graft/resolver/check.go |
+| LANE, re-land | `landAttempt`, `landingAttempt.decide`, `landWithResolution` | operations/land.go, land_attempt.go, land_reland.go |
+| 3-way merge, listing | `landingAttempt.decide`, `landListConflicts` | operations/land_attempt.go, land_resolve.go |
+| per-file verdicts, decide | `resolveLandConflicts`, `landAnswerProposes` (planned: `decideLand`) | operations/land_resolve.go, land_proposals.go |
+| classify | `landClassify`, `resolver.SendRules` | operations/land_resolve.go; graft/resolver |
+| operator rules, file checks | `Resolver.resolveFile`, `Resolver.runChecks`, `syntax.CheckMerge` | tools/graft-agents/resolve/resolve.go |
+| AI per file | `llmStrategy.Resolve`, `ResolveLLM`, `llmResolvePatch` | tools/.../resolve/llm_strategy.go, llm_core.go, llm_patch.go |
+| regions, assemble | `llmRegions`, `llmAssemble` | tools/.../resolve/llm_core.go |
+| one call per region, its checks | `llmPatchSystem`, `llmPatchUser`, `llmPatchAnswer`, `llmCheckPatched`, `llmCheckAnswer` | tools/.../resolve/llm_patch.go, llm_core.go |
+| proposal mark, no recording | `proposer`, `Resolver.resolveFile` | tools/.../resolve/llm_strategy.go, resolve.go |
+| verify.command | `landVerify`, `verifyRejected` | operations/land_verify.go, land_resolve.go |
+| merge commit, trailers | `landWriteResolution` | operations/land_resolve.go |
+| PACKAGE | `landWithPackage`, `landListing.conflictPackage` | operations/land_package.go |
+| proposals, hidden reference | `landWriteProposals`, `landUpdateProposalRefs`, `landPruneProposals` | operations/land_proposals.go |
+| refs/graft/ reserved for the server | `graftReservedDenial` | gitaly/hook/referencetransaction.go |
+| composition report | (planned) | (planned: graft/resolver, with a parity-tested copy in tools/) |
+
+### 15.6 The composition check, measured: a report, not a gate
+
+The design first meant the check to turn a proposal into a landable resolution (Federico's
+amendment, 14): every edit of each side must appear in the result unless the other side's edit to
+the same base lines supersedes it. Measured with zero model calls:
+
+* **Definition, from the principle, frozen before measuring** (sha256 9396326b..., checked before
+ every run). A hunk is contested when the other side edited overlapping base lines (or touches it,
+ for an insertion); the result may compose a contested hunk freely, so it is never a drop. An
+ uncontested hunk must be in the result. Duplicates and changes outside the conflicts fail.
+ Disclosure: before freezing it, 8 human resolutions from the 300 had been looked at with an
+ earlier, stricter prototype; the frozen definition is measured on cases outside the 300.
+* **Human resolutions outside the 300** (2644 content cases): 82.6% pass; 324 change lines outside
+ the conflicts, 103 duplicate, 32 drop.
+* **Power.** Something verifiable (an uncontested hunk, or a line both sides added) exists in 20.0%
+ of those cases and 19.2% of their regions (300: 29.9% of cases, 11.6% of regions). A diff3
+ region exists because both sides edited overlapping base lines, so most regions are wholly
+ contested and pass vacuously.
+* **As a gate on R1b's accepted answers:** without it 143 of 244 correct, 58.6% [95% CI 52.3-64.6];
+ with it, 135 of 220 passes correct, 61.4% [54.8-67.6]. 175 of the 220 passes are vacuous (64.6%
+ correct); the verified passes are 48.9% correct [35.0-63.0]. If only passes landed, 73% of the
+ conflicts would land and about 39% of those would be wrong. The gate does not move precision.
+* **Contested regions have no line-level property.** A stricter prototype (every line either side
+ added present unless superseded line by line) separated better on R1 (74.5% precision) but was
+ built while looking at those cases, is still far below a landing bar (~90%), and fails half of the
+ human merges (the right resolution of a contested statement is often a third version that holds
+ neither side's line). Composition inside a contested region is semantic; a line-level check only
+ measures overlap with the sides.
+
+**Decisions.**
+1. The AI stays proposal-only.
+2. Federico's amendment (AI landing when every deterministic check passes) stays recorded and is
+ not enabled: no deterministic check reaches the bar. Pending the Sol-100 result, which Federico
+ uses to decide.
+3. The composition report goes with every proposal, honest about what it can say: "keeps every
+ uncontested change of both sides" or "drops THEIRS' change at base 40-44", "duplicates a line
+ both sides added", "changes lines outside the conflicts", "N contested regions resolved freely".
+ The duplicates flag carries signal (7 of 19 correct where it fires, against 58.6% overall): it is
+ useful in the report and as a repair trigger.
+4. The repair round (when approved) is driven only by deterministic findings with their exact
+ wording: anchors, syntax, and the composition report's drops and duplicates where they apply.
+5. The design work goes to what helps the agent decide: the report, symmetric context (each side's
+ change from the base and its intent), and abstaining (the model may answer that the changes do
+ not compose, which reaches the agent as abstained with the reason).
+
+**Java.** R1b's Java answers are 54 of 54 correct (Wilson 95% CI 93.4-100). That is a property of the
+model on these cases, not of the check, and most of them come from one repository (spring-boot).
+It is a candidate for a per-language, measured policy, which would first need validation on Java
+cases from other repositories.
+
+### 15.7 Other resolvers, compared
+
+From the PM's survey (17 tools and papers; prompts read from source where the licence allowed).
+GitButler's AI resolve is described here from the PM's account of it; its code was not read.
+
+* GitButler sends one structured JSON request per commit with every hunk; we send one call per
+ region. Our own R0 (whole-file JSON) against R1 (per region) on the same 300 cases: 53.8% against
+ 41.8% strict error, and R0 -> R1b significantly more correct (McNemar p = 0.018). Per region stays.
+* GitButler writes each resolution into both sides and lets git merge again, which keeps the
+ non-conflicting changes; our llmAssemble rebuilds the file from the base, the clean regions and
+ the resolved ones. The two are equivalent when the regions are those of git's own merge; to be
+ adopted as an assertion test of llmAssemble (planned): writing the result into both sides and
+ merging must give the assembled file.
+* GitButler lands directly with no semantic check; ours proposes, with a report. That, and the
+ measured finding that a line-level check cannot gate, is where gitai differs.
+* Credit: the patch-application structure of R1 is synthmerge's (Andrea Arcangeli; GPL, structure
+ only, our own wording and example). The evidence on scope (ConflictAgent, Shen 2026, MIT; Rover,
+ CC BY) and on intent (GitWand, Copilot, MIT) informed the planned symmetric context. The design,
+ the composition report and its measurement are gitai's.