diff --git a/Parallel-Agents-and-Conflicts.-.md b/Parallel-Agents-and-Conflicts.-.md new file mode 100644 index 0000000..a51b263 --- /dev/null +++ b/Parallel-Agents-and-Conflicts.-.md @@ -0,0 +1,49 @@ +# Parallel agents and conflict resolution + +Each independent prompt starts from an accepted state and receives its own +worktree. Multiple agents can therefore read, edit, and test the same codebase +without sharing a mutable working directory. + +## Compatible work + +Hop uses Git's real three-way content merge: + +- disjoint files compose automatically; +- independent hunks in the same file compose automatically; +- identical same-file changes coalesce; and +- compatible rename/content and mode/content changes can compose. + +Before acceptance, Hop validates the exact integrated tree rather than trusting +tests run only against an agent's stale starting point. + +## Genuine conflicts + +When Git cannot compose both intents, `hop land` exits with code `20` and +creates a fresh reconciliation attempt. The response includes: + +- a reconciliation prompt state; +- a new isolated workspace; +- current accepted and proposed inputs; and +- conflict candidate paths. + +The agent switches to that workspace, preserves both compatible intents, +resolves the conflict, runs `hop check`, creates a new proposal, and lands again. +Hop requires successful checked evidence before a reconciliation proposal can +be frozen. + +Text conflicts usually contain diff3 markers. Delete/rename, binary, symlink, +mode, and directory conflicts may not, so the agent must inspect both input +states rather than assuming the provisional tree is resolved. + +## What still needs a person + +The agent should stop only when the source conflict exposes a real product +decision—for example, two prompts require mutually exclusive API behavior and +neither recorded intent determines the right result. Ordinary code overlap is +not user work. + +## Visible-root safety + +The selected project directory remains at the last accepted state while +reconciliation is underway. If that folder has user-owned divergence, Hop does +not overwrite it; `hop land` exits with code `23` and reports the paths.