From 11b169b064471a4ffd930abdb601f48e7272b8f9 Mon Sep 17 00:00:00 2001 From: Chris Busillo Date: Sun, 31 May 2026 09:14:40 -0400 Subject: [PATCH] chore(upstream): add review cursor tracking --- .github/github.json | 9 ++- .github/upstream-cursors.json | 41 ++++++++++ AGENTS.md | 10 +++ docs/upstream-import-policy.md | 34 +++++++++ justfile | 4 + scripts/local/upstream-cursors.sh | 123 ++++++++++++++++++++++++++++++ 6 files changed, 220 insertions(+), 1 deletion(-) create mode 100644 .github/upstream-cursors.json create mode 100755 scripts/local/upstream-cursors.sh diff --git a/.github/github.json b/.github/github.json index 1556d7649f7..cb97c6b2ccc 100644 --- a/.github/github.json +++ b/.github/github.json @@ -3,6 +3,11 @@ "projectType": "every-code-product", "upstreamForkBaseBranch": "fork-main", "productBranch": "main", + "upstreamReviewTracking": { + "cursorFile": ".github/upstream-cursors.json", + "policyDoc": "docs/upstream-import-policy.md", + "statusCommand": "just local-upstream-cursors" + }, "docs": { "overview": "README.md", "agentGuide": "AGENTS.md", @@ -29,6 +34,7 @@ }, "scripts": { "waitForGitHubRun": "scripts/wait-for-gh-run.sh --workflow Release --branch main", + "upstreamCursors": "just local-upstream-cursors", "upstreamImport": "just local-upstream-import", "localReleaseNotes": "just local-release-notes" }, @@ -114,7 +120,8 @@ "GitHub default branch changes", "Every Code default branch changes", "release workflow changes", - "upstream mirror policy changes" + "upstream mirror policy changes", + "upstream review cursor changes" ] } } diff --git a/.github/upstream-cursors.json b/.github/upstream-cursors.json new file mode 100644 index 00000000000..b57f44b6d7d --- /dev/null +++ b/.github/upstream-cursors.json @@ -0,0 +1,41 @@ +{ + "schemaVersion": 1, + "productBranch": "main", + "updatedAt": "2026-05-31T13:00:00Z", + "upstreams": { + "justEveryCode": { + "remote": "upstream", + "branch": "main", + "repository": "just-every/code", + "role": "fork upstream/import source", + "lastExamined": { + "commit": "7065f1689ebf85e40323cad6c7b1e67de8fed015", + "examinedAt": "2026-05-31T13:00:00Z", + "basis": "reviewed for import candidates" + }, + "lastImported": { + "commit": null, + "importedAt": null, + "method": null, + "productCommit": null + } + }, + "openaiCodex": { + "remote": "openai", + "branch": "main", + "repository": "openai/codex", + "role": "original upstream/provenance source", + "lastExamined": { + "commit": "cdde711fac008cd4e1115603ead713cf23b1a580", + "examinedAt": "2026-05-31T13:00:00Z", + "basis": "reviewed direct upstream provenance delta" + }, + "lastImported": { + "commit": null, + "importedAt": null, + "method": null, + "productCommit": null + } + } + } +} diff --git a/AGENTS.md b/AGENTS.md index 441e953a5de..5abad18b21a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,6 +99,16 @@ Examples: fetches `upstream/main`, merges it into the current Every Code branch, replays any commits listed in `scripts/local/upstream-picks.txt`, then rebuilds the release binary. +- Use `just local-upstream-cursors` to inspect the durable upstream review + cursors in `.github/upstream-cursors.json`. `lastExamined` means the newest + upstream commit whose delta has been reviewed or intentionally skipped; + `lastImported` means the newest upstream commit actually merged, cherry-picked, + or manually ported into Every Code. Do not infer either value from + `git merge-base` alone. +- Advance `.github/upstream-cursors.json` only after reviewing the new range for + that upstream. Keep cursor changes in the PR that performs the review/import + so future sessions compare from the recorded `lastExamined` SHA instead of + rereading older commits. - Commits already on the product branch persist automatically across future upstream imports. They do not need to be duplicated in `scripts/local/upstream-picks.txt`. diff --git a/docs/upstream-import-policy.md b/docs/upstream-import-policy.md index 751c71dcc9c..25e1db7ce25 100644 --- a/docs/upstream-import-policy.md +++ b/docs/upstream-import-policy.md @@ -115,6 +115,40 @@ source unless the conflict touches one of those owned areas. Keep `scripts/local/upstream-picks.txt` empty unless a patch intentionally lives outside the product branch and must be replayed. +### Upstream Review Cursors + +Every Code is a long-running overlay product with two upstream references. Track +where review left off in `.github/upstream-cursors.json`, and inspect that state +with: + +```sh +just local-upstream-cursors +``` + +The cursor file records `lastExamined` and `lastImported` separately for each +upstream source: + +- `lastExamined` is the newest upstream commit whose delta has been reviewed or + intentionally skipped. This is the cursor future sessions should compare from + to avoid rereading old upstream commits. +- `lastImported` is the newest upstream commit actually merged, cherry-picked, or + manually ported into Every Code. It can be older than, newer than, or absent + relative to `lastExamined`, especially for direct `openai/codex` provenance + reviews. + +Do not infer either value from `git merge-base`. Merge bases are useful branch +health diagnostics, but they do not say what a human or agent already examined. + +When reviewing upstream without importing, advance only `lastExamined` for that +source after the review is complete. When importing or manually porting upstream +work, update `lastImported` as well and include the product commit that contains +the port. Keep cursor changes in the same PR as the review/import so the next +session can start from the recorded SHA. + +Fetch branch refs without tags when checking cursors. Upstream and Every Code +share `v*` tag names, and tag fetches can collide even when branch refs are +healthy. + ## Release Cadence Cut an Every Code release after every successful upstream import or local hotfix diff --git a/justfile b/justfile index 9f232cbb135..fc3e0420af4 100644 --- a/justfile +++ b/justfile @@ -75,6 +75,10 @@ local-remove-homebrew-code-link: local-upstream-import: ./scripts/local/update-from-upstream.sh +[no-cd] +local-upstream-cursors *args: + ./scripts/local/upstream-cursors.sh "$@" + [no-cd] local-release-notes: ./scripts/local/release-notes.sh diff --git a/scripts/local/upstream-cursors.sh b/scripts/local/upstream-cursors.sh new file mode 100755 index 00000000000..34269b66d0b --- /dev/null +++ b/scripts/local/upstream-cursors.sh @@ -0,0 +1,123 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$repo_root" + +metadata="$repo_root/.github/github.json" + +if [[ ! -f "$metadata" ]]; then + echo "error: metadata file not found: $metadata" >&2 + exit 1 +fi + +fetch_refs=true +if [[ "${1:-}" == "--no-fetch" ]]; then + fetch_refs=false +elif [[ $# -gt 0 ]]; then + echo "usage: $0 [--no-fetch]" >&2 + exit 1 +fi + +cursor_file_relative="$(jq -r '.upstreamReviewTracking.cursorFile // empty' "$metadata")" +if [[ -z "$cursor_file_relative" ]]; then + echo "error: upstreamReviewTracking.cursorFile is missing from $metadata" >&2 + exit 1 +fi + +cursor_file="$repo_root/$cursor_file_relative" +if [[ ! -f "$cursor_file" ]]; then + echo "error: cursor file not found: $cursor_file_relative" >&2 + exit 1 +fi + +product_branch="$(jq -r '.productBranch // .defaultBranch // "main"' "$cursor_file")" + +if ! git rev-parse --verify --quiet "$product_branch^{commit}" >/dev/null; then + echo "error: product branch '$product_branch' is not available locally" >&2 + exit 1 +fi + +mapfile -t cursor_keys < <(jq -r '.upstreams // {} | keys[]' "$cursor_file") +if [[ ${#cursor_keys[@]} -eq 0 ]]; then + echo "error: no upstream entries found in $cursor_file_relative" >&2 + exit 1 +fi + +if [[ "$fetch_refs" == true ]]; then + for key in "${cursor_keys[@]}"; do + remote="$(jq -r --arg key "$key" '.upstreams[$key].remote' "$cursor_file")" + branch="$(jq -r --arg key "$key" '.upstreams[$key].branch' "$cursor_file")" + echo "Fetching $remote/$branch" + git fetch "$remote" "$branch" >/dev/null + done + echo +fi + +product_head="$(git rev-parse --short=12 "$product_branch")" +echo "Product branch: $product_branch ($product_head)" +echo "Cursor file: $cursor_file_relative" +echo + +for key in "${cursor_keys[@]}"; do + remote="$(jq -r --arg key "$key" '.upstreams[$key].remote' "$cursor_file")" + branch="$(jq -r --arg key "$key" '.upstreams[$key].branch' "$cursor_file")" + repository="$(jq -r --arg key "$key" '.upstreams[$key].repository // "unknown"' "$cursor_file")" + role="$(jq -r --arg key "$key" '.upstreams[$key].role // "upstream source"' "$cursor_file")" + last_examined="$(jq -r --arg key "$key" '.upstreams[$key].lastExamined.commit // empty' "$cursor_file")" + last_imported="$(jq -r --arg key "$key" '.upstreams[$key].lastImported.commit // empty' "$cursor_file")" + remote_ref="$remote/$branch" + + echo "[$key] $repository" + echo " role: $role" + echo " remote ref: $remote_ref" + echo " lastExamined: ${last_examined:-missing}" + echo " lastImported: ${last_imported:-not recorded}" + + if [[ -z "$last_examined" ]]; then + echo " status: missing lastExamined cursor" + echo + continue + fi + + missing=false + if ! git rev-parse --verify --quiet "$remote_ref^{commit}" >/dev/null; then + echo " status: remote ref is not available locally" + missing=true + fi + if ! git rev-parse --verify --quiet "$last_examined^{commit}" >/dev/null; then + echo " status: lastExamined commit is not available locally" + missing=true + fi + if [[ "$missing" == true ]]; then + echo + continue + fi + + remote_head="$(git rev-parse "$remote_ref")" + remote_head_short="$(git rev-parse --short=12 "$remote_ref")" + if [[ "$remote_head" == "$last_examined" ]]; then + review_delta=0 + else + review_delta="$(git rev-list --count "$last_examined..$remote_ref")" + fi + + read -r product_only remote_only < <(git rev-list --left-right --count "$product_branch...$remote_ref") + merge_base="$(git merge-base "$product_branch" "$remote_ref")" + merge_base_short="$(git rev-parse --short=12 "$merge_base")" + + echo " remote head: $remote_head_short" + echo " merge-base: $merge_base_short" + echo " review delta: $review_delta commits after lastExamined" + echo " branch delta: $product_only product-only / $remote_only upstream-only" + + if [[ "$review_delta" != "0" ]]; then + echo " new commits:" + git log --oneline --max-count=10 "$last_examined..$remote_ref" | sed 's/^/ /' + remaining=$((review_delta - 10)) + if ((remaining > 0)); then + echo " ... plus $remaining more" + fi + fi + echo +done