feat: catch up the review base from the nearest saved ancestor

[Svilen-Stefanov]

Stacked on #139 (feat/base-provenance); review and merge that first.

What changed and why

With no saved base for the merge base and no usable baseline committed there, a review analyzed the merge base from scratch, even when a saved analysis of a commit a few steps below it was already in the artifact store. That is the slowest path a review has, and the common one right after setup.

• scripts/action/find-ancestor-base.sh (new): walks the merge base's first-parent history (git rev-list --first-parent, after deepening the shallow checkout to 101 commits), then pages through GET /repos/{repo}/actions/artifacts?per_page=100 newest first, keeping non-expired codeboarding-base-<cfg>-* artifacts produced by a run on the repository's own code (the same head_repository_id == repository_id rule as fetch-state.sh). It stops at the first page holding a walked commit and takes the nearest one seen. Bases are published as commits are synced or reviewed, so that is one or two calls in practice and 50 pages at most, against GITHUB_TOKEN's 1,000 requests an hour per repository, and only on a run that would otherwise analyze from scratch. Seeding keeps the merge base's own .codeboardingignore and health configuration. It downloads it through fetch-state.sh, so the exact-name lookup and provenance check run again on the one it uses.
• Review order is now: exact artifact, committed at the merge base, nearest ancestor (bound: 100 first-parent commits), full. The ancestor seeds an incremental catch-up to the merge base (["incremental", "incremental"] with the head), and the caught-up base is published as the exact codeboarding-base-<cfg>-<merge_base> artifact, so later PRs forking there hit it directly. Fork runs still never publish it.
• Reporting: base_source=ancestor, base_from_sha=<A>, catchup_commits=<N>. base_reason=too_far_behind only when the walk reached the bound and one of up to five saved analyses is confirmed (compare API) to be an ancestor; a failed deepen or another branch's analysis gives no_baseline. A saved analysis of the merge base under another configuration reports incompatible.
• Sync uses the same lookup when the branch has no usable committed baseline (including the tip itself), so the first sync after the setup PR merges catches up from the base the setup PR's preview review saved instead of running full. The token is unset before the engine runs. force_full still skips all seeding.
• FORCE_FULL is lowercased with tr instead of ${,,}, so analyze.sh and its tests also run on macOS's bash 3.2.
• Docs: base-resolution table and metadata rows in docs/COMMIT_STRATEGY.md.

Why a committed baseline still ranks above an ancestor artifact

A baseline committed at the merge base is in the checkout already: no listing, no download. It is what sync writes for that branch, and sync publishes artifacts for the same two commits, so an ancestor artifact nearer than the committed baseline's own commit would be one of those, describing the same tree. Ranking it first saves the listing on every review of a repository that commits its baseline.

What it looks like

This PR changes nothing visible in the web platform UI by itself. On GitHub the comment can now say:

<sub>Base: caught up 4 commits from main @a1b2c3d, 41 s · changes 2 m 39 s</sub>
<sub>Base: built from scratch (saved diagram too far behind), 8 m 54 s · changes 3 m 12 s</sub>

How it was tested

New tests in tests/test_action_state.py (AncestorSeedTests), against real git histories and a stubbed gh: nearest ancestor found within the bound (and the nearer of two wins, published under the merge base's name), ancestor beyond the bound (too_far_behind), a saved analysis off this history (no_baseline, not far behind), an ancestor uploaded by a run on forked code (rejected, never downloaded), another configuration at the merge base (incompatible), a depth-1 clone deepened to find the ancestor, lookup disabled (no API calls), first sync after setup (incremental only), forced sync (no lookup), a busy store paged to page 12 and no further, another branch's newer analysis not hiding a real far ancestor, a cut-short walk never called too far behind, and the merge base's config surviving the seed.

python -m unittest discover -s tests: 224 tests, all pass locally (macOS). Black 25.9.0 via the pre-commit hook; shellcheck on all action scripts.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T15:34:47.046176Z	32fdc42	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[codeboarding-review]

CodeBoarding review

Status: 0 changed components (no analysed file changed)

See the full change in CodeBoarding.

_{Base: caught up 2 commits from feat/base-provenance @a7675d5, 29 s · changes 10 s}

graph LR
    n_action_scripts["action_scripts"]
    classDef added fill:#1f883d,stroke:#0b5d23,color:#ffffff;
    classDef modified fill:#bf8700,stroke:#7d4e00,color:#ffffff;
    classDef deleted fill:#cf222e,stroke:#82071e,color:#ffffff,stroke-dasharray:5 3;

Loading

_{download artifacts · run 37644619965}

[ivanmilevtues]

I think all my comments from #139 are actually for #140.

I think this split in particular is not really good, as it is a stack which defines its funcitonality in the base but doesn't really have it, so I got puzzled. I thought it defined the things which are defined in this PR.

I will proly re-review after we change the language in the base, as that might prily will change how things look here and I won't have to remap names and things