add blockers log

Author: jasonhawkharris

AGENTS.md

@@ -28,7 +28,9 @@ change. Never regenerate snapshots to conceal a regression. If correctness is
 uncertain, stop.
 
 Before stopping at an incompatible upstream commit, remove that commit from the
-sync branch and leave the worktree clean at the last successful commit. Report:
+sync branch, append an entry to
+[`docs/scip-ruby/SORBET_SYNC_BLOCKERS.md`](docs/scip-ruby/SORBET_SYNC_BLOCKERS.md),
+commit that documentation change, and leave the worktree clean. Report:
 
 - the last successfully incorporated upstream SHA
 - the incompatible upstream SHA, subject, and GitHub link

docs/scip-ruby/CONTRIBUTING.md

@@ -354,6 +354,8 @@ This will correctly use the `scip-ruby/master` branch as the target.
 Follow the [Sorbet synchronization runbook](./SYNCING_SORBET.md). It describes
 the commit-by-commit process, validation, progress tracking, and the requirement
 to stop before the first upstream commit that needs an indexer adaptation.
+Each such stop is recorded in the
+[Sorbet synchronization blocker log](./SORBET_SYNC_BLOCKERS.md).
 
 Do not modify existing commits or rewrite the history of `scip-ruby/master`.
 Once a completed sync is passing, temporarily turn on "Allow merge commits" in

docs/scip-ruby/SORBET_SYNC_BLOCKERS.md

@@ -0,0 +1,31 @@
+# Sorbet synchronization blockers
+
+This log records each Sorbet commit that stopped the upstream synchronization
+process because scip-ruby required an indexer adaptation. It preserves the
+reason for each stop, the proposed work, and the eventual resolution.
+
+Add entries chronologically. Use one entry per blocking upstream commit. If a
+later sync attempt encounters the same commit, update its existing entry rather
+than creating a duplicate. When the adaptation lands, change its status to
+`Resolved` and link the resolving pull request or commit.
+
+<!--
+Copy this template when the synchronization process stops:
+
+## YYYY-MM-DD — Sorbet `<short SHA>`: <commit subject>
+
+- **Status:** Blocked
+- **Last incorporated Sorbet commit:** `<SHA>`
+- **Blocking Sorbet commit:** [`<SHA>`](https://github.com/sorbet/sorbet/commit/<SHA>)
+- **Upstream change:** <Describe the changed API or representation.>
+- **Indexer impact:** <Explain why the current indexer cannot compile or produce
+  correct SCIP output. Name affected scip-ruby files and symbols.>
+- **Evidence:** <Include concise compiler errors, test failures, or code
+  evidence.>
+- **Required adaptation:** <Describe the concrete proposed implementation.>
+- **Tests:** <Describe tests to add or update.>
+- **Open questions:** None, or list unresolved design decisions.
+- **Resolution:** Pending
+-->
+
+No blockers have been recorded yet.

docs/scip-ruby/SYNCING_SORBET.md

@@ -13,7 +13,9 @@ each newly incorporated Sorbet mainline commit. A run has two valid outcomes:
 1. It reaches the fixed target SHA, passes final validation, and updates
    `scip_ruby_sync_upstream_sorbet_sha`.
 2. It stops immediately before the first commit that requires an indexer
-   change, leaving a clean branch and a precise adaptation report.
+   change, records the blocker in
+   [`SORBET_SYNC_BLOCKERS.md`](./SORBET_SYNC_BLOCKERS.md), and leaves a clean
+   branch with a precise adaptation report.
 
 Never implement the required indexer adaptation as part of the discovery run.
 After that adaptation has been reviewed and implemented separately, start or
@@ -187,8 +189,13 @@ At the first commit requiring an indexer change:
    git reset --hard "$LAST_SAFE_SHA"
    ```
 
-5. Confirm there is no active cherry-pick and `git status --short` is empty.
-6. Record the incompatible SHA as the next unprocessed commit in the local state
+5. Append a complete entry to `docs/scip-ruby/SORBET_SYNC_BLOCKERS.md` using its
+   template. If that upstream SHA already has an entry, update it instead of
+   adding a duplicate.
+6. Commit only the blocker-log change with a message such as
+   `docs: record Sorbet sync blocker <short SHA>`.
+7. Confirm there is no active cherry-pick and `git status --short` is empty.
+8. Record the incompatible SHA as the next unprocessed commit in the local state
    file.
 
 The blocker report must include:
@@ -204,10 +211,14 @@ The blocker report must include:
 - unresolved design choices or uncertainty
 - confirmation that the incompatible commit is not on the branch and the
   worktree is clean
+- the blocker-log entry and its commit
 
 Report only the first incompatible commit. Later commits may depend on a design
 decision made while adapting to this one.
 
+When the indexer adaptation is later implemented, update the corresponding log
+entry to `Resolved` and link its pull request or commit in the resolution field.
+
 ## Finish a completed sync
 
 After every worklist commit through `TARGET_SHA` has passed: