From 071891475bce5fac7e50d407ca854f7678893400 Mon Sep 17 00:00:00 2001 From: cyph3rasi Date: Sat, 11 Jul 2026 15:14:22 -0700 Subject: [PATCH] Document automatic accepted-state publishing --- Agent-Workflow.md | 6 +++++- Architecture.md | 5 +++++ CLI-Reference.md | 1 + Core-Concepts.md | 10 ++++++++++ Getting-Started.md | 5 +++++ Home.md | 3 ++- Security-and-Privacy.md | 5 +++++ Troubleshooting.md | 12 ++++++++++++ 8 files changed, 45 insertions(+), 2 deletions(-) diff --git a/Agent-Workflow.md b/Agent-Workflow.md index 048e8f1..90d55a0 100644 --- a/Agent-Workflow.md +++ b/Agent-Workflow.md @@ -34,7 +34,9 @@ hop land R_... -- go test ./... ``` No second landing authorization is requested unless the user explicitly asks -for review-first behavior. +for review-first behavior. After acceptance, Hop automatically pushes the +accepted commit when the repository has an unambiguous upstream. The agent does +not ask the user to run `git push`. Skill-based capture stores the agent's verbatim transcription of the visible message and its attachment references. Because the skill runs after the client @@ -84,6 +86,8 @@ can only guarantee capture before project effects. - Never edit the canonical project root directly. - Never mutate a frozen proposal. +- Inspect landing warnings. If automatic push failed transiently, retry once + with `hop push`; never force-push a diverged remote. - Do not bypass `hop land` with Git reset, checkout, worktree, or manual copying. - Run validation against immutable checkpoints and the final integrated tree. - Let Hop merge compatible concurrent work. diff --git a/Architecture.md b/Architecture.md index c80e00b..0089eb2 100644 --- a/Architecture.md +++ b/Architecture.md @@ -50,5 +50,10 @@ 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. +After that local transaction succeeds, Hop attempts a non-forced push of the +accepted commit to the inferred upstream branch. Remote publication is derived +and retryable: its failure cannot roll back or corrupt the durable local +acceptance. + For the full product direction, read the [product blueprint](https://githop.xyz/GnosysLabs/Hop/src/branch/main/docs/product-blueprint.md). diff --git a/CLI-Reference.md b/CLI-Reference.md index 21267c6..c5b7e41 100644 --- a/CLI-Reference.md +++ b/CLI-Reference.md @@ -34,6 +34,7 @@ release. |---|---| | `hop accept PROPOSAL [-- COMMAND...]` | Accept internally without changing visible files | | `hop sync` | Materialize the current accepted tree from a safe accepted ancestor | +| `hop push` | Retry publishing the current accepted commit to its inferred upstream | | `hop undo` | Create a forward-only acceptance that restores the previous accepted tree | | `hop doctor [--repair]` | Validate database/object/ref consistency | diff --git a/Core-Concepts.md b/Core-Concepts.md index 4e53f31..6884511 100644 --- a/Core-Concepts.md +++ b/Core-Concepts.md @@ -59,3 +59,13 @@ 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. + +## Automatic upstream push + +Every successful accepted transition is automatically pushed to the active +branch's configured Git upstream. If no upstream is set, Hop uses `origin`, or a +single unambiguous remote, with the active branch name. It pushes only accepted +commits—not prompts, checkpoints, proposals, SQLite history, or workspaces—and +never force-pushes. A network, authentication, or non-fast-forward failure +leaves the accepted local state intact and is returned as a warning for the +agent to handle. diff --git a/Getting-Started.md b/Getting-Started.md index 62cd559..a6b7991 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -48,6 +48,11 @@ hop doctor A normal interactive result reports `Root: synchronized`. +If the active Git branch has an upstream—or the repository has one unambiguous +`origin`/single-remote destination—landing also fast-forward pushes the accepted +commit automatically. Hop never force-pushes. Repositories without a remote +remain local without treating that as an error. + ## Ask for review before landing Automatic landing is the default because the original task authorizes the diff --git a/Home.md b/Home.md index 3d8b554..3a4ede4 100644 --- a/Home.md +++ b/Home.md @@ -3,7 +3,8 @@ Hop is prompt-native version control for coding agents. It stores each prompt as an immutable project state, gives agent work an isolated workspace, validates the exact tree being accepted, and safely materializes accepted results into the -visible project folder. +visible project folder. When a Git upstream exists, accepted commits are pushed +automatically. ## Start here diff --git a/Security-and-Privacy.md b/Security-and-Privacy.md index bf6b918..ac26378 100644 --- a/Security-and-Privacy.md +++ b/Security-and-Privacy.md @@ -46,6 +46,11 @@ Hop does not use `reset --hard`, move the active branch, or write the user's real Git index. Visible-root synchronization fails closed when files, ignored destinations, or staged state could be overwritten. +Automatic push delegates authentication to the user's existing Git transport +and credential configuration. Hop does not store remote passwords, SSH private +keys, or access tokens. It disables terminal credential prompting in the +background push path and redacts detected credentials from returned errors. + ## Reporting a vulnerability Before the public security contact is configured, disclose vulnerabilities diff --git a/Troubleshooting.md b/Troubleshooting.md index 72f16dd..988fa7b 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -73,6 +73,18 @@ hop doctor --repair Do not repair while a final validation command is running. +## Automatic push failed + +The accepted state remains safe locally. Hop never force-pushes. Retry a +transient network or authentication failure with: + +```bash +hop push +``` + +If the remote branch moved independently, preserve both histories and resolve +the divergence intentionally; do not replace this with a force-push. + ## A secret was pasted Rotate it. Hop redaction reduces durable exposure but cannot prove that every