Reconcile Gitea distribution with current alpha behavior and release tooling

Hop-State: A_06FN55REVAR7VQG4BWJBCD8 Hop-Proposal: R_06FN55QTEWKH16NSR59YJYG Hop-Task: T_06FN3MBF98GWD4NA5PA1RWG Hop-Attempt: AT_06FN55BQ80H2S8WHNDD24G0
2026-07-11 12:10:59 -07:00
parent 23a4891099
commit de99aad4d4
28 changed files with 1565 additions and 21 deletions
@@ -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.