Add bounded PR-detail fill

[joshka]

Parent: #81

Observed Workflow

After using coverage-style SQL to find missing PR details, I needed to hydrate those missing rows. This was useful for maintainer work, but the orchestration lived outside Gitcrawl.

Some repositories were practical to fill. Larger ones looked likely to take hours, cross multiple GitHub API resets, and add hundreds of MB or multiple GB to the local DB.

Current Workaround

The manual workflow involved:

• selecting PRs missing detail rows
• batching PR numbers
• running targeted syncs with PR-detail hydration
• watching GitHub API quota remaining/reset times
• deciding whether to sleep through a reset or stop
• estimating remaining time and DB growth
• retrying transient failures
• re-running SQL to confirm completion

Request

Add a bounded PR-detail fill command.

Example shape:

gitcrawl fill-pr-details owner/repo --limit 500 --reserve-rate-limit 500 --json-progress

Useful Behavior

• select only PRs missing detail rows
• support ordering such as newest-first, oldest-first, or open-first
• optionally include comments, reviews, files, checks, and workflow runs
• report GitHub quota remaining and reset time
• stop or sleep before exhausting quota
• emit progress suitable for long-running terminal or Codex-agent sessions
• resume cleanly from a previous partial run

Why This Matters

The use case is not "hydrate everything blindly." It is local maintainer visibility: fill enough of the archive to answer real questions, while keeping quota, time, and disk growth bounded.

Acceptance Criteria

• Can fill only missing PR details for one repo.
• Has a limit flag.
• Has JSON progress output.
• Reports quota/reset information during long runs.
• Can stop safely and be resumed.

---

Prepared with Codex, confirmed as accurate by human.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 1, 2026, 10:38 PM ET / 02:38 UTC.

Summary
Keep open: current main and v0.6.4 still lack a bounded fill-pr-details command, and #89 is an open closing implementation candidate rather than a merged fix.

Reproducibility: not applicable. this is a feature request, not a bug report. Source and docs inspection confirms current main only supports manual number-targeted PR-detail hydration.

Root-cause cluster
Relationship: canonical
Canonical: #83
Summary: This issue is the canonical bounded PR-detail fill request, and the linked pull request is its current implementation candidate.

Members:

• fixed_by_candidate: Add bounded PR detail fill command #89 - The pull request body closes this issue and implements the same bounded fill-pr-details command.
• partial_overlap: Track initial local maintainer-archive use friction #81 - The parent maintainer-archive friction tracker delegates bounded PR-detail fill to this narrower issue.
• adjacent_distinct: Add archive coverage reporting #82 - Coverage reporting can identify missing PR details but is a separate command request.
• adjacent_distinct: Track failed sync and hydration attempts #84 - Failed hydration attempt tracking is related operationally but asks for a separate failure ledger.
• adjacent_distinct: Document initial local maintainer-archive workflows #87 - Documentation of archive workflows is related but does not implement the bounded fill command.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
An open closing PR already owns the implementation, so ClawSweeper should not queue a duplicate issue-fix PR.

Review details

Best possible solution:

Review and either land or reject #89; after it merges, close this issue as implemented while keeping coverage and failure-ledger follow-ups separate.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature request, not a bug report. Source and docs inspection confirms current main only supports manual number-targeted PR-detail hydration.

Is this the best way to solve the issue?

Yes, the narrow solution is a focused command layered on the existing syncer and PR-detail store paths. The open linked PR is the right implementation candidate to review before this issue closes.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The linked implementation PR is still open, so closing this issue now would drop the canonical tracker before the requested command reaches main.
• Maintainers still need to accept the first-version command, flag, ordering, and quota behavior before the feature becomes the supported path.

Codex review notes: model internal, reasoning high; reviewed against 4b8c52e37cc6.

Label changes

Label changes:

• add clawsweeper:linked-pr-open: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.
• remove clawsweeper:queueable-fix: Current issue advisory state no longer selects this label.
• remove clawsweeper:fix-shape-clear: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is a low-risk maintainer-ergonomics feature for bounded local archive hydration, not an urgent runtime regression.
• impact:other: The issue affects maintainer archive completeness and quota-bounded local visibility, which is meaningful but outside the specific owned impact categories.

Evidence reviewed

What I checked:

• Current CLI has no fill command: The main command switch lists sync, threads, runs, search, and other commands, but no fill-pr-details command. (internal/cli/app.go:137, 4b8c52e37cc6)
• Existing manual hydration primitive: runSync supports --numbers, --include-pr-details, and --with pr-details, so users can hydrate known PR numbers but the command does not select locally missing PR-detail rows. (internal/cli/app.go:2622, 4b8c52e37cc6)
• Syncer hydrates selected PR rows only: PR details are fetched only when IncludePRDetails is set for a selected pull_request row, leaving missing-row selection outside the current syncer path. (internal/syncer/syncer.go:156, 4b8c52e37cc6)
• Docs expose sync but not bounded fill: The command reference documents gitcrawl sync ... --numbers ... --with pr-details but not a bounded fill-pr-details command. (docs/commands.md:44, 4b8c52e37cc6)
• No fill symbols on main: Source search found no fill-pr-details, runFillPRDetails, MissingPullRequestDetailNumbers, reserve-rate-limit, or json-progress implementation on the reviewed main checkout. (4b8c52e37cc6)
• Open closing PR exists: GitHub reports Add bounded PR detail fill command #89 as open, mergeable, and closing this issue; its head adds the requested command but is not merged. (e0621ab1cb09)

Likely related people:

• steipete: GitHub path history shows Peter Steinberger introduced and maintained PR-detail caching and hydration code that this command would build on. (role: feature-history owner; confidence: high; commits: 7222fef197b4, 5232d51cdde2, e37bc375db75; files: internal/syncer/pull_details.go, internal/store/pull_requests.go)
• vincentkoc: Local blame on the current release snapshot and GitHub path history connect Vincent Koc to current CLI dispatch and adjacent app command code. (role: recent area contributor; confidence: medium; commits: 4b8c52e37cc6, e5546915e491, bd7ef8461294; files: internal/cli/app.go)
• joshka: Recent merged work by Josh McKinney changed PR-detail storage behavior that a missing-detail fill command would reuse. (role: adjacent PR-detail contributor; confidence: medium; commits: dca4f0d7b6df; files: internal/store/pull_requests.go, internal/store/pull_requests_test.go)
• TurboTheTurtle: The open linked pull request implements the requested bounded fill command and explicitly closes this issue. (role: candidate fix author; confidence: high; commits: e0621ab1cb09; files: internal/cli/app.go, internal/cli/app_test.go, internal/store/pull_request_fill.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

🦞🔧
ClawSweeper is automatically building this issue.

The issue review finished and no active implementation pull request was found.

Automatic implementation progress:

• State: Queued
• Detail: Review complete; no active implementation PR was found. The Codex implementation worker is queued.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27879835453
• Updated: 2026-06-20T18:20:35.895Z
• Opt out: add clawsweeper:manual-only or clawsweeper:human-review.