diff --git a/.agents/skills/gitcrawl/SKILL.md b/.agents/skills/gitcrawl/SKILL.md index eaf5a686..7d4807ea 100644 --- a/.agents/skills/gitcrawl/SKILL.md +++ b/.agents/skills/gitcrawl/SKILL.md @@ -1,6 +1,6 @@ --- name: gitcrawl -description: Use for local GitHub issue/PR archive search, sync freshness, clusters, durable maintainer triage, gh-shim cache reads, and Gitcrawl repo/release work. +description: Use for local GitHub issue/PR archive search, sync freshness, clusters, durable maintainer triage, handoff to Octopool-backed gh reads, and Gitcrawl repo/release work. --- # Gitcrawl @@ -55,8 +55,8 @@ gitcrawl sync owner/repo --numbers 123,456 --with pr-details ``` `--with pr-details` hydrates PR files, commits, checks, workflow runs, and -review-thread resolution state. Use it when cached PR status reports missing PR -details, unknown checks, or unknown review-thread resolution. +review-thread resolution state in the local archive. Use it when the review +needs those details; it does not populate Octopool's separate `gh` cache. For agent-driven discovery, prefer bounded freshness: @@ -77,29 +77,35 @@ Common commands: gitcrawl search issues "query" -R owner/repo --state open --json number,title,url gitcrawl clusters owner/repo --sort size --min-size 5 gitcrawl cluster-detail owner/repo --id -gitcrawl gh pr status 123 -R owner/repo --compact -gitcrawl gh pr view 123 -R owner/repo --json number,title,state,url +gitcrawl threads owner/repo --numbers 123 --include-closed --json ``` -For PR triage, start with cached status, then drill down only into blockers: +For an exact PR, read the archive with `threads` first. `--include-closed` +keeps closed or merged candidates in scope; archive state is not proof of +current GitHub state. Then use bare PATH `gh` for fresh metadata when needed, +including before final merge/comment decisions: ```bash -gitcrawl gh pr status -R owner/repo --compact -gitcrawl gh pr view -R owner/repo --json number,title,state,url,isDraft,headRef,headSha -gitcrawl gh pr checks -R owner/repo --json name,state,conclusion,detailsUrl +gh pr view 123 -R owner/repo --json number,title,state,url,isDraft,headRefName,headRefOid ``` -`pr status` exits `0` clean, `1` action needed, `2` error, or `3` pending. Use `--live` before final merge/comment decisions when liveness matters; it refreshes exact PR details/review threads, then returns the same normalized status shape. Use `--cached` when measuring local cache coverage. +Drill down into checks only when needed: -Readiness is conservative: non-open PRs, drafts, failing/unknown checks, -pending checks, merge conflicts or blocked/unknown mergeability, unresolved or -unknown review threads, active requested changes, and missing approval block -ready. Bodyless approvals count. Review state is the latest non-stale decision -per reviewer, so a later approval supersedes an earlier changes-requested. +```bash +gh pr checks 123 -R owner/repo --json name,state,bucket,link +``` + +Keep the existing Octopool-backed `gh` shim and use narrow JSON field lists so +supported reads share its cache. Native `gh` uses `headRefName`/`headRefOid` +for PR refs and `bucket`/`link` for check classification and URLs, not the old +Gitcrawl field names. -Default `pr status` may auto-hydrate when the PR row exists but PR details or -review-thread markers are missing. `GITCRAWL_GH_AUTO_HYDRATE=0` and `--cached` -keep it local-only. +`gitcrawl gh` is removed and exits `2` with a migration note. Do not retry its +`status`, `view`, or `checks` recipes, pass its `--live`/`--cached` flags to +`gh`, or rebuild an older Gitcrawl to recover that cache. This is a command +migration, not an authentication failure: do not run `octopool login`, change +tokens, auth, PATH, or config, or bypass the existing shim to repair it. See +[the gh migration guide](../../../docs/gh-shim.md) for ownership and first-time setup. ## SQL @@ -128,9 +134,9 @@ a verified `openclaw/gitcrawl` checkout before concluding the feature is missing ## Maintainer Boundaries `close-thread`, `close-cluster`, exclusions, and canonical-member choices are -local maintainer overrides; they do not write back to GitHub. Set -`GITCRAWL_GH_PATH` explicitly when using the gh shim so it cannot recurse into -itself. +local maintainer overrides; they do not write back to GitHub. Use bare PATH +`gh` for authorized GitHub writes; Octopool handles fallback to the real CLI. +Gitcrawl no longer owns the `gh` shim or its configuration. ## Verification @@ -146,6 +152,6 @@ Then run targeted CLI smoke for the touched surface, for example: gitcrawl doctor --json gitcrawl status --json gitcrawl search issues "test" -R openclaw/gitcrawl --state open --limit 5 -gitcrawl gh --live pr status https://github.com/openclaw/openclaw/pull/ --compact -gitcrawl gh pr status https://github.com/openclaw/openclaw/pull/ --compact +gitcrawl threads owner/repo --numbers 123 --include-closed --json +gh pr view 123 -R owner/repo --json number,title,state,url,headRefOid ``` diff --git a/docs/gh-shim.md b/docs/gh-shim.md index efc644a9..59128bb4 100644 --- a/docs/gh-shim.md +++ b/docs/gh-shim.md @@ -12,7 +12,29 @@ permalink: /gh-shim/ Gitcrawl no longer owns a GitHub CLI compatibility cache. Gitcrawl remains the local per-repo mirror, portable store, search, clustering, and triage tool. Octopool owns the org-authenticated shared GitHub cache and pooled read relay. -## Migrate +## Existing Octopool setup + +Keep local discovery in Gitcrawl, then use the existing bare PATH `gh` for fresh GitHub metadata: + +```bash +gitcrawl threads owner/repo --numbers 123 --include-closed --json +``` + +```bash +gh pr view 123 -R owner/repo --json number,title,state,url,isDraft,headRefName,headRefOid +``` + +```bash +gh pr checks 123 -R owner/repo --json name,state,bucket,link +``` + +Archive state can lag GitHub; verify current state before a final maintainer action. Keep narrow JSON reads on the existing Octopool-backed `gh` shim so they use its shared cache. Do not bypass it with an absolute path to the real GitHub CLI. + +The retired `gitcrawl gh` exits `2`; this migration notice is not an authentication failure. If the shim already works, do not run `octopool login` or change tokens, authentication, PATH, or configuration to replace those recipes. The old Gitcrawl `pr status` readiness/exit-code contract, `--live`/`--cached` flags, and `GITCRAWL_GH_*` cache controls do not apply to bare `gh`. Use native field names: `headRefName`/`headRefOid` for PR refs and `bucket`/`link` for checks, rather than `headRef`/`headSha` or `conclusion`/`detailsUrl`. + +## First-time Octopool setup + +Only for an operator setting up a new Octopool installation: ```bash octopool login diff --git a/docs/maintainer-archive.md b/docs/maintainer-archive.md index 4dc2d306..91b2d333 100644 --- a/docs/maintainer-archive.md +++ b/docs/maintainer-archive.md @@ -88,14 +88,17 @@ For broad backlog sweeps, keep the first pass metadata-only. Hydrate comments an ## Know the Octopool boundary -Gitcrawl owns the local SQLite mirror, search, clustering, TUI, and read-only JSON control surfaces. Octopool owns pooled live `gh` reads: +Gitcrawl owns the local SQLite mirror, search, clustering, TUI, and read-only JSON control surfaces. Octopool owns pooled live `gh` reads. For an exact candidate, read the archive first, then verify fresh metadata through the existing bare PATH `gh`: ```bash -octopool login -octopool gh api repos/openclaw/gitcrawl/issues/82 +gitcrawl threads owner/repo --numbers 123 --include-closed --json ``` -Use `gitcrawl search` and `gitcrawl cluster-detail` for local discovery. Use Octopool, or the real `gh` CLI when you need to write, for final live verification, comments, labels, PR creation, and other GitHub mutations. +```bash +gh pr view 123 -R owner/repo --json number,title,state,url,headRefOid +``` + +Use `gitcrawl search` and `gitcrawl cluster-detail` for broader local discovery. Keep JSON reads on the existing Octopool-backed `gh` shim; use that same bare `gh` for authorized GitHub mutations, which Octopool forwards to the real CLI. Do not bypass the shim or change authentication, tokens, PATH, or configuration to replace retired `gitcrawl gh` recipes. See [gh shim migration](/gh-shim/) for the archive/cache boundary and separate first-time setup. ## First-run checklist @@ -105,4 +108,4 @@ Use `gitcrawl search` and `gitcrawl cluster-detail` for local discovery. Use Oct 4. Search locally with `--sync-if-stale` when freshness matters. 5. Use `sync --numbers` to hydrate only the candidate issues or pull requests you are actively triaging. 6. Check `gitcrawl runs owner/repo --kind sync --json` if freshness or last-run status is unclear. -7. Use Octopool or real `gh` for final live GitHub reads and all write actions. +7. Read exact candidates with `gitcrawl threads --numbers`; use the existing bare PATH `gh` for final live GitHub reads and authorized write actions.