Initial Hop alpha

2026-07-11 07:33:41 -07:00
commit 675135b77e
19 changed files with 5612 additions and 0 deletions
@@ -0,0 +1,108 @@
+# Hop agent protocol
+
+## State graph
+
+```text
+A accepted
+├─ P prompt, persisted before effects
+│  └─ C checkpoint
+│     └─ R proposal
+└─ P independent prompt
+
+A + R ──land──> A next accepted state
+```
+
+State prefixes:
+
+| Prefix | Kind | Meaning |
+|---|---|---|
+| `A_` | accepted | Canonical project revision |
+| `P_` | prompt | Exact instruction and pre-effect context |
+| `C_` | checkpoint | Immutable workspace progress |
+| `R_` | proposal | Frozen candidate result |
+| `F_` | failed | Durable failed execution or validation state |
+| `X_` | cancelled | Durable cancelled state |
+
+Prompt, checkpoint, and proposal states may reference identical Git trees while remaining distinct causal occurrences.
+
+## Environment contract
+
+| Variable | Purpose |
+|---|---|
+| `HOP_ROOT` | Canonical project root containing `.hop/hop.db` |
+| `HOP_STATE_ID` | Prompt state authorizing the current instruction |
+| `HOP_TASK_ID` | Logical task grouping related prompts and attempts |
+| `HOP_ATTEMPT_ID` | Current agent approach/run |
+| `HOP_WORKSPACE` | Only directory the agent may modify |
+
+Treat missing variables as an invalid agent launch. Do not infer an attempt from a nearby worktree when causality matters.
+
+## Command contract
+
+### Human or controller
+
+```bash
+hop init
+hop start --agent <name> "<exact initial prompt>"
+hop env <prompt-state>
+hop prompt --from <state> "<exact follow-up prompt>"
+hop land <proposal> -- <final validation command>
+hop undo
+```
+
+`hop start` creates the task, attempt, prompt state, and detached workspace before returning. The controller may deliver the prompt only after exit `0`.
+
+`hop prompt` captures a checkpoint of current workspace effects before creating the follow-up prompt state.
+
+### Agent
+
+```bash
+hop state "$HOP_STATE_ID" --json
+hop status --json
+hop check "$HOP_STATE_ID" -- <command>
+hop propose --summary "<summary>" "$HOP_STATE_ID"
+```
+
+`hop check` snapshots the attempt and runs the command in a detached worktree materialized from that exact checkpoint. Edits made concurrently in the live workspace do not change the tested tree.
+
+`hop propose` freezes the current nonignored workspace tree. Later workspace edits cannot change the proposal.
+
+`hop land` compares paths changed by the proposal with paths accepted since its base. Any shared changed path blocks landing. Disjoint proposals are composed with Git three-tree plumbing and may then be validated on the final tree.
+
+## Exit codes
+
+| Code | Meaning |
+|---:|---|
+| `0` | Success |
+| `1` | Git, SQLite, filesystem, or internal error |
+| `2` | Invalid CLI usage |
+| `20` | Overlap or conservative conflict block |
+| `21` | Accepted or attempt head changed during compare-and-swap |
+| `22` | Validation command failed |
+
+A failed `hop check` or final landing check persists its evidence. A blocked or failed landing does not advance accepted state.
+
+## Human launch sequence
+
+```bash
+hop init
+hop start --agent codex "Add password reset emails"
+```
+
+Use the returned workspace and environment to launch the agent. For example, conceptually:
+
+```bash
+eval "$(hop env P_...)"
+<agent-command> "<the same exact prompt>"
+```
+
+The exact agent command is harness-specific. Until a Hop process adapter intercepts prompts automatically, follow-up prompts must also pass through `hop prompt` before the agent acts.
+
+## Failure handling
+
+- **Missing Hop environment:** stop before editing and request a Hop-controlled launch.
+- **Check failure:** fix the live workspace, checkpoint/check again, then create a new proposal.
+- **Frozen proposal needs changes:** record a follow-up prompt; never mutate the stored proposal.
+- **Overlap on landing:** retain both lineages and reconcile through a new prompt against current accepted state.
+- **Ref inconsistency:** run `hop doctor`; use `hop doctor --repair` only outside final validation.
+- **Secrets:** prompt text and check output are stored locally without encryption in the alpha. Never place credentials in them.