Hop
68d8bf2f7d
Hop-State: A_06FN69X2VW0BAXG4A4DT6V0 Hop-Proposal: R_06FN69VET1STZNKPWK913K8 Hop-Task: T_06FN637799RW5Q7WH9H6PJR Hop-Attempt: AT_06FN63779BJRBK1VFQ94GRR
55 lines
1.6 KiB
Markdown
55 lines
1.6 KiB
Markdown
# Architecture
|
|
|
|
Hop uses Git under the hood, but it is not merely a directory of metadata files
|
|
inside `.git`.
|
|
|
|
## Git responsibilities
|
|
|
|
Git provides:
|
|
|
|
- content-addressed blobs and trees;
|
|
- synthetic commits for immutable snapshots;
|
|
- detached worktrees for attempt isolation;
|
|
- three-way merge behavior;
|
|
- diffs and path inspection; and
|
|
- interoperability with existing repositories.
|
|
|
|
Hop never needs to move the user's active branch or rewrite the real index.
|
|
Private objects are pinned beneath `refs/hop/states/*`; accepted history is
|
|
mirrored at `refs/hop/accepted`.
|
|
|
|
## Hop responsibilities
|
|
|
|
`.hop/hop.db` is a SQLite WAL database containing:
|
|
|
|
- prompt/task/attempt identity;
|
|
- typed state edges and accepted lineage;
|
|
- evidence tied to exact source trees;
|
|
- session heads for interactive-agent follow-ups;
|
|
- materialized-root state; and
|
|
- immutable audit events.
|
|
|
|
## Project layout
|
|
|
|
```text
|
|
.hop/
|
|
├── hop.db
|
|
├── workspaces/
|
|
├── checks/
|
|
├── integration/
|
|
└── *.lock
|
|
```
|
|
|
|
`.hop/` is added to `.git/info/exclude`, not the public `.gitignore`. Hop refuses
|
|
initialization when `.hop` is already tracked as user-owned project content.
|
|
|
|
## Acceptance consistency
|
|
|
|
Acceptance is serialized and compare-and-swapped. SQLite is authoritative;
|
|
derived Git refs can be repaired by `hop doctor --repair`. Visible-root landing
|
|
also tracks which accepted state is physically visible, allowing safe catch-up
|
|
with `hop sync` without treating a divergent folder as disposable.
|
|
|
|
For the full product direction, read the
|
|
[product blueprint](https://githop.xyz/GnosysLabs/Hop/src/branch/main/docs/product-blueprint.md).
|