Hop
2f00b2dd3f
Hop-State: A_06FN5XPBA1JMJNPS2MAR0D0 Hop-Proposal: R_06FN5XN2CX7XBZ4KF1JZZ2G Hop-Task: T_06FN3MBF98GWD4NA5PA1RWG Hop-Attempt: AT_06FN5TMC0J7DXV2JGF15T20
61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# Core concepts
|
|
|
|
Hop versions intent and source together. Git remains the content store; Hop adds
|
|
the causal state graph that explains which instruction produced which result.
|
|
|
|
## States
|
|
|
|
| Prefix | State | Meaning |
|
|
|---|---|---|
|
|
| `A_` | Accepted | Canonical Hop project revision |
|
|
| `P_` | Prompt | Durable instruction and pre-effect context |
|
|
| `C_` | Checkpoint | Immutable snapshot of attempt progress |
|
|
| `R_` | Proposal | Frozen candidate result |
|
|
| `F_` | Failed | Durable failed execution or validation result |
|
|
| `X_` | Cancelled | Terminal cancelled result |
|
|
|
|
Two states can reference the same Git tree and still be distinct occurrences.
|
|
For example, a prompt and checkpoint may contain identical files but represent
|
|
different moments and causal roles.
|
|
|
|
## Task
|
|
|
|
A task groups the prompts and attempts pursuing one user outcome. Follow-up
|
|
messages pursuing unfinished work stay connected automatically through
|
|
`CODEX_THREAD_ID`. Once that outcome is accepted, the next message starts a new
|
|
Hop task at the latest accepted state even when the Codex conversation stays
|
|
open.
|
|
|
|
## Attempt and workspace
|
|
|
|
An attempt is one agent approach. Each attempt has a detached Git worktree under
|
|
`.hop/workspaces/`. Agents edit there instead of racing in the visible project
|
|
root.
|
|
|
|
## Evidence
|
|
|
|
`hop check` snapshots the workspace and runs validation against that immutable
|
|
tree. Evidence stores the command, redacted output, exit code, and exact tree
|
|
hash.
|
|
|
|
## Proposal
|
|
|
|
`hop propose` freezes a candidate tree. Later workspace edits cannot mutate the
|
|
proposal.
|
|
|
|
## Landing
|
|
|
|
`hop land` composes the proposal onto the current accepted state, runs optional
|
|
final-tree validation, advances accepted history with compare-and-swap, and
|
|
safely materializes the result into the visible project directory.
|
|
|
|
`hop accept` is lower-level controller behavior: it advances internal accepted
|
|
state but intentionally leaves the visible folder unchanged.
|
|
|
|
## Visible root
|
|
|
|
The visible root is the project directory selected in Codex. Hop only
|
|
materializes into it when it still matches an accepted Hop ancestor. Untracked,
|
|
ignored, staged, or ordinary file divergence that could be overwritten causes a
|
|
fail-closed error.
|