vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs, prompts, hive-forge: stop handing readers the renamed verbs

Browse source 
docs/tools/forge.md already listed the nine renamed verbs as removed, then
used them ~30 more times in pasteable blocks. Sweeps every occurrence a
reader would type, including three runtime messages that told the user to
run a verb the same binary rejects.

The renamed-verb list itself keeps the old names; it is what documents them.

Refs #4155
This commit is contained in:
atlas 2026-09-10 15:56:20 +02:00 • committed by mara
commit 55f01942a2
23 changed files with 73 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/integrations/knowledge.md
View file

@ -120,7 +120,7 @@ required.
though you can't push a branch:
```sh
hive-forge -r internal/knowledge pr-create --agit \
hive-forge -r internal/knowledge pr create --agit \
--title "docs: add the X runbook" \
--topic add-x-runbook \
--body-file - <<'EOF'

2
docs/process/pr-review-gate.md
View file

@ -28,7 +28,7 @@ is someone else's call.
## Reviewers: submit the verdict, don't gate it on CI
Submit `hive-forge pr-reviews <pr> --approve` or `--request-changes`
Submit `hive-forge pr reviews <pr> --approve` or `--request-changes`
as soon as you've finished checking the diff — don't hold it back
waiting for CI to go green first. Mention CI's current state in the
review body if it's relevant (for example "approving; `nix flake check` is

2
docs/scheduler/ci.md
View file

@ -62,7 +62,7 @@ Forgejo's PR commit-status tracking appears scoped to `pull_request`-event
runs specifically, so a dispatched run — even a genuinely successful one —
never writes to that status slot. Reproduced with three dispatches on one
PR over 20+ minutes, all genuinely green, the PR's own status unmoved
throughout. **Always re-check `pr-status` after a dispatch and believe
throughout. **Always re-check `pr status` after a dispatch and believe
what it says — don't push a commit just to unwedge it, that's the
empty-commit anti-pattern this verb exists to avoid.** If `hive-forge
ci-log --run <n> --job 0` shows the code green (verdict is the

66
docs/tools/forge.md
View file

@ -75,22 +75,22 @@ hive-forge issue reaction 42 add heart # react to issue 42 with :heart:
hive-forge issue reaction 42 --comment 18042 add +1 # react to a specific comment instead
hive-forge issue reaction 42 remove heart # remove your own :heart: reaction
hive-forge issue reaction 1 --list-allowed # this instance's actual configured shortcodes
hive-forge issue-create --title "..." --body "..."
hive-forge issue-create --title "..." --body "..." --label area/ops --label type/bug # repeatable
hive-forge issue-edit 42 --title "new title"
hive-forge issue create --title "..." --body "..."
hive-forge issue create --title "..." --body "..." --label area/ops --label type/bug # repeatable
hive-forge issue edit 42 --title "new title"
hive-forge pr edit 42 --title "new title" # same edit, PR-kind-validated
hive-forge pr 42 # PR metadata as JSON
hive-forge pr-create --title "..." --head my-branch --push # also `git push forge my-branch`
hive-forge pr-create --title "..." --head my-branch --label area/ops # repeatable, same as issue-create
hive-forge pr-reviews 42 # list reviews; inline comments included per review
hive-forge pr-reviews 42 --approve # submit APPROVED review
hive-forge pr-reviews 42 --request-changes -m "msg" # submit REQUEST_CHANGES review
hive-forge pr-reviews 42 --comment -m "msg" # submit COMMENT review
hive-forge pr create --title "..." --head my-branch --push # also `git push forge my-branch`
hive-forge pr create --title "..." --head my-branch --label area/ops # repeatable, same as issue create
hive-forge pr reviews 42 # list reviews; inline comments included per review
hive-forge pr reviews 42 --approve # submit APPROVED review
hive-forge pr reviews 42 --request-changes -m "msg" # submit REQUEST_CHANGES review
hive-forge pr reviews 42 --comment -m "msg" # submit COMMENT review
hive-forge pr assign-reviewer 42 argus # set argus as a requested reviewer on the PR
hive-forge pr assign-reviewer 42 argus --remove # withdraw the request
hive-forge pr assign-committer 42 damocles # add damocles to the PR's assignee list
hive-forge diff 42 # unified diff (lockfile hunks collapsed by default)
hive-forge diff 42 --full # include unfiltered lockfile hunks
hive-forge pr diff 42 # unified diff (lockfile hunks collapsed by default)
hive-forge pr diff 42 --full # include unfiltered lockfile hunks
hive-forge list # open issues/PRs
hive-forge list --kind pr --state all --page 2 # page 2 of all PRs (walk --page 1,2,… with --limit as page size for a repo-wide sweep)
hive-forge list --search "trust bundle" --state all # full-text over title AND body — the duplicate check
@ -105,11 +105,11 @@ hive-forge lint no-reviewer --reviewer argus # PRs where argus specifically isn
hive-forge lint stale-branches --days 14 # branches with no recent activity, each with its merge outcome (PR #n merged / closed unmerged / no PR)
hive-forge lint assignments # per-assignee open item count
hive-forge lint unlabeled --scope type # open issues/PRs with no exclusive type/* label (any scope works, e.g. --scope area)
hive-forge pr-status --pr 42 # PR health: mergeable, CI, reviews, last comment (exit 0 = ready)
hive-forge pr-status --sha <sha> # CI-only fast path for an explicit commit sha
hive-forge pr-merge 42 # merge (refuses unless mergeable + CI not red + no changes-requested); deletes head branch
hive-forge pr-merge 42 --method rebase # rebase-merge instead of a merge commit (no squash option)
hive-forge pr-merge 42 --keep-branch --force # keep the head branch; override the readiness gate
hive-forge pr status --pr 42 # PR health: mergeable, CI, reviews, last comment (exit 0 = ready)
hive-forge pr status --sha <sha> # CI-only fast path for an explicit commit sha
hive-forge pr merge 42 # merge (refuses unless mergeable + CI not red + no changes-requested); deletes head branch
hive-forge pr merge 42 --method rebase # rebase-merge instead of a merge commit (no squash option)
hive-forge pr merge 42 --keep-branch --force # keep the head branch; override the readiness gate
hive-forge timeline 42 # audit trail: closes, label changes, assignments, commit refs
hive-forge attach-issue 42 /path/to/file # upload a file attachment to an issue; prints download URL
hive-forge attach-comment 18042 /path/to/file # upload a file attachment to a comment; prints download URL
@ -121,7 +121,7 @@ hive-forge subscription --watch # subscribe to repo notifications
hive-forge subscription --unwatch # unsubscribe
hive-forge subscription --list # list every repo you watch (audit the notification firehose)
hive-forge -r internal/knowledge clone # clone with creds auto-injected
hive-forge -r internal/knowledge pr-create --agit --topic foo --title "..." # open PR via AGit (no fork)
hive-forge -r internal/knowledge pr create --agit --topic foo --title "..." # open PR via AGit (no fork)
# --- repo management ---
hive-forge repo-create my-repo # create under authenticated user; prints URL
hive-forge repo-create my-repo --org myorg --private --auto-init # under an org, private, with initial commit
@ -144,16 +144,16 @@ distinct output shape — pick by what you need:
| Only the comments (skip the body), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) are merged in too | `comments <n>` [`--tail N`] | comment + review-body list; **marks read** |
| One specific comment by its id | `comment-show <id>` | single comment |
| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list |
| The code change | `diff <n>` | unified diff |
| Is this PR ready to merge — mergeable + CI + reviews | `pr-status --pr <n>` | health view; exit code = merge-readiness |
| The review verdicts + inline review comments | `pr-reviews <n>` | review list |
| The code change | `pr diff <n>` | unified diff |
| Is this PR ready to merge — mergeable + CI + reviews | `pr status --pr <n>` | health view; exit code = merge-readiness |
| The review verdicts + inline review comments | `pr reviews <n>` | review list |
Rule of thumb: **`view` first** when you're about to act on a thread (it
shows everything and clears the unread guard so your follow-up `comment`
isn't rejected); the JSON verbs (`issue`/`pr`) when a script needs one
field; `pr-status` when the only question is "can I merge it."
field; `pr status` when the only question is "can I merge it."
### Contributing to a read-only repo (`clone` + `pr-create --agit`)
### Contributing to a read-only repo (`clone` + `pr create --agit`)
Agents are read-only collaborators on some repos (e.g.
`internal/knowledge`) and so can't push branches. Forgejo's AGit flow
@ -165,7 +165,7 @@ hive-forge -r internal/knowledge clone # clone, auth handled for you
cd knowledge
# add / edit / delete any files, then commit normally
git add -A && git commit -m "add foo runbook"
hive-forge -r internal/knowledge pr-create --agit \
hive-forge -r internal/knowledge pr create --agit \
--topic foo-runbook \ # groups pushes into ONE PR; reuse to update it
--title "add foo runbook" \
[--body "details"] # PR description (also accepts --body-file)
@ -177,17 +177,17 @@ URL and the `origin` remote it leaves behind carry no credentials —
`clone` instead configures `origin`'s `credential.helper` to invoke
`hive-forge credential-helper` (a hidden verb, not meant to be run by
hand), which git calls fresh on every fetch/push. That's what lets
`pr-create --agit` (default remote `origin`) push without re-auth,
`pr create --agit` (default remote `origin`) push without re-auth,
without a durable token sitting in the checkout's `.git/config`.
`pr-create --agit` prints the PR URL. Re-running with the same
`pr create --agit` prints the PR URL. Re-running with the same
`--topic` force-updates the existing open PR (the AGit ref is
agent-owned scratch). Opens a reviewable PR the operator merges — never
commits straight to `main`.
`hive-forge <verb> --help` prints the full signature for any verb.
### `pr-status`
### `pr status`
One-stop PR health view (`--pr <n>`): mergeable state, CI checks,
requested reviewers + review verdicts, and the last-comment timestamp —
@ -197,11 +197,11 @@ before merge). `--sha <sha>` is a CI-only fast path for a raw commit.
A failing/erroring CI context prints its job link. The process exit code
is a **merge-readiness** verdict for `--pr` (0 only when CI is green AND
the PR is mergeable AND no review requests changes), so it composes:
`hive-forge pr-status --pr 42 && echo ready`. `--sha` mirrors the CI
`hive-forge pr status --pr 42 && echo ready`. `--sha` mirrors the CI
verdict alone.
```
hive-forge pr-status --pr 42
hive-forge pr status --pr 42
# PR #42: feat(...): ... # lint:allow: sample CLI output, not a real tag
# state: open (mergeable: yes)
# CI: e39a87ea3949: ✅ success (1 context(s))
@ -264,21 +264,21 @@ to discover valid label names before triaging or to audit the label set.
block), or pass `--force` to skip the guard.
- `comment --body "..."` with backticks in the body: always use
`--body-file -` with a HEREDOC to avoid shell escaping issues.
- `pr-create --push` also runs `git push forge <head>` and suppresses
- `pr create --push` also runs `git push forge <head>` and suppresses
the post-push "Create a pull request" hint (hive-forge prints the
canonical URL itself).
- `attachment-get` saves to `/tmp/forge-attachment-{uuid}` by default
and prints the resolved path. Pass `-o -` to stream to stdout.
- `artifact-get <name> --run <n>` downloads a CI Actions artifact. `<n>`
is the run number from the run-page URL (`/actions/runs/<n>`, which
`pr-status` surfaces as a CI context's target_url). Forgejo 15 serves
`pr status` surfaces as a CI context's target_url). Forgejo 15 serves
artifacts only via the web route, not REST, and keys that route by
the run's internal global id, so the verb translates the run number
first. Saves a zip to `/tmp/forge-artifact-<name>.zip` by default; pass
`-o -` to stream to stdout.
- `ci-log --run <n> [--job i] [--step i] [--attempt n]` prints a CI
run's job step logs. `<n>` is the run number from the run-page URL
(same value `artifact-get` takes; `pr-status` surfaces it as a CI
(same value `artifact-get` takes; `pr status` surfaces it as a CI
context's target_url). Two log sources, tried in **completeness
order**: the verb tries the **durable persisted-log download** the run page's "view
raw logs" link uses (`…/runs/<n>/jobs/<job>/attempt/<a>/logs`, a flat
@ -327,12 +327,12 @@ to discover valid label names before triaging or to audit the label set.
instance-global, this path ignores `<n>`/`--comment`.
- **Don't** use raw `curl` for forge access -- the CLI handles auth,
error checking, and output formatting.
- `issue-create --label <name>` / `pr-create --label <name>` are
- `issue create --label <name>` / `pr create --label <name>` are
repeatable and take the same spelling `labels <n> add` does. **An
unknown name is an error, not a silent drop** — the command fails
listing the names that didn't resolve plus every label the repo has,
so it's fixable from the message without a second call. On
`pr-create --agit`, hive-forge applies labels as a follow-up call once
`pr create --agit`, hive-forge applies labels as a follow-up call once
it parses the PR number back out of the push output (the AGit push
itself has no label field), so they're silently skipped if that
parse fails — same fallback as the deferred multi-line body.