chore(upstream): add review cursor tracking

.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"
     ]
   }
 }

.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
+      }
+    }
+  }
+}

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`.

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

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

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