Hop
68d8bf2f7d
Hop-State: A_06FN69X2VW0BAXG4A4DT6V0 Hop-Proposal: R_06FN69VET1STZNKPWK913K8 Hop-Task: T_06FN637799RW5Q7WH9H6PJR Hop-Attempt: AT_06FN63779BJRBK1VFQ94GRR
62 lines
2.3 KiB
Markdown
62 lines
2.3 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
|
|
a stable session ID supplied by the integration. Codex Desktop supplies
|
|
`CODEX_THREAD_ID` automatically. Once that outcome is accepted, the next message
|
|
starts a new Hop task at the latest accepted state even when the client
|
|
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 an agent client or passed
|
|
as the controller's working directory. 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.
|