grok-sync

Sync the vendored Grok Build tree (third_party/grok-build) forward to a newer upstream release: measure the pin against upstream HEAD, inventory the changelog delta, build a per-item adoption matrix,

SKILL.md

GitHub

Grok Build sync (vendored tree, ADR-0008)

The product base is open-source Grok Build, vendored at third_party/grok-build/ and pinned by SOURCE_REV (ADR-0008). Upstream ships near-daily; dsb falls behind whenever nobody syncs. This skill is the procedure so a future session inherits it instead of re-deriving it.

Companions: grok-sync-runbook (normative steps) · GROK_VENDOR (layout, patch re-apply) · UPSTREAM_SYNC_LEDGER (what past syncs decided).


0. Ground truth first — never assume

./scripts/grok-sync-inventory.sh          # pin vs upstream HEAD, delta, clusters

The script prints: the pin and the upstream commit it corresponds to, upstream HEAD and its version, the release delta, file/crate counts, and the changelog bullet inventory for the covered range. Read it before planning anything.

Two facts to establish that the script cannot know:

Question How
Does the current tree actually equal the pinned upstream commit? git archive <commit> | tar -x -C /tmp/base then diff -rq /tmp/base third_party/grok-build -x target -x .git — a small diff is the dsb overlay, a large one means the tree drifted
Do the carried patches still apply? ./scripts/apply-grok-build-patches.sh --check

If the overlay is large (hundreds of files) or the patches conflict, rsync --delete + re-apply is not the method — go to §3 (three-way merge).


1. Decide what is worth taking — per item, with a reason

Read every changelog in the covered range. They live at crates/codegen/xai-grok-shell/changelogs/<version>.md in both trees.

Classify every bullet into exactly one bucket, and write the reason:

Verdict Means
Take Behavior dsb should have; carry it and test it
Hold Right idea, wrong time — record why and what would change the answer
Reject Against dsb's identity (NON_GOALS, HARNESS_PHILOSOPHY) — say which
N/A xAI-hosted surface with no dsb meaning (see §2)

"Upstream has it" is not a reason. The source ladder is L1 Deep Code > L2 Reasonix > L3 Grok, and L3 never overrides L1/L2 (SOURCES). An upstream change that breaks snippet-edit semantics, prefix-cache stability, or permission honesty is a Reject no matter how nice it looks.

Breaking changes get a verdict too

Upstream arbitrary breaking changes can hit dsb specs. Read them explicitly and record the impact — a removed tool parameter, a changed default, a moved file.


2. The xAI-hosted surface is not a port target

Upstream contains zero DeepSeek code. These clusters are frequently N/A — check each rather than blanket-rejecting:

telemetry/consent · xAI login, OIDC, team policy · billing and credit upsell · grok self-update channels · voice · video generation and ZDR · image generation · Desktop / Computer-Hub daemon · x.ai/* RPC method names · GROK_* env vars and ~/.grok paths.

But be careful: many of those releases also carry general work in the same file (a TUI fix, a session fix). Split the bullet, not the release.


3. The merge — three-way, never rsync --delete

When the overlay is non-trivial, a raw tree swap loses dsb's work and the patch series will not re-apply (upstream moves the same files).

Role Tree
merge base the old upstream commit the vendored tree was pinned to
ours current third_party/grok-build/ (base + dsb overlay)
theirs the new upstream commit

Do it in a scratch repo outside the product tree (e.g. ~/Personal/Projects/OpenSources/_upstream/), then copy the merged result in. Reconcile each conflict by asking: is this change upstream's to take, or dsb's to keep? A conflict where both sides changed the same line is a design decision, not a mechanical one.

Then carry the overlay explicitly — these are dsb's, not upstream's:

  • DeepSeek sampling — prompt_cache_hit_tokens → cached_read_tokens
  • DeepSeek status extension — x.ai/deepseek/status (balance/session usage)
  • Status line rendering — the DeepSeek balance row
  • Prompt identity — no hardcoded third-party vendor claim in the agent prompt, and its encrypted copy must be regenerated
  • Seeded product changelog — the version-transition cleanup must not delete $GROK_HOME/CHANGELOG.md
  • DeepSeek themes — deepseeknight*.rs plus their registration in the picker, cache, appearance, and syntax tables
  • Path A cache signal / spec-10 assembly helpers
  • Invocation branding — quit/relaunch hints print dsb, not grok

Regenerate the patch series from the new base; the previous series is superseded. Update docs/architecture/GROK_VENDOR.md's tables to match.


4. Prove it — gates, then build

./scripts/build-grok-pager.sh check      # vendor tree compiles
./scripts/test-owner-bar.sh              # must stay green
./scripts/check-path-a-linkage.sh
./scripts/test-heart-regression.sh
./scripts/test-grok-vendor-offline.sh
./scripts/test-product-offline.sh
./scripts/check-semver.sh

Vendored Grok builds are serial across all worktrees — a cold build is 30–60+ minutes and parallel builds starve each other. Check pgrep -fl 'grok-build/target' before starting, and say so in the PR if you waited.

Report honestly: a gate that did not run is not green. Paste the commands and their real outcome.


5. Record it — three artifacts, no more

Artifact For
docs/product/UPSTREAM_SYNC_LEDGER.md The next session. Pin before → after, versions covered, verdict counts, the decisions that need context, gates, PR number.
docs/product/CHANGELIST_<VER>.md The owner. Plain-language answer to "what is better now, and why" — grouped by what the reader feels (faster / fixed / new / changed), with a not-taken section. One file.
docs/research/grok-build.md The record. The sync's adoption matrix, version by version.

Then, if the sync justifies a major, follow the release skill. The MAJOR gate reads docs/product/versions/README.md — add the row before releasing.


Anti-patterns

Don't Why
rsync -a --delete over a non-trivial overlay Silently drops dsb's work; the patch series will not re-apply
Porting a GROK_*/~/.grok/xAI-hosted item "for completeness" Ships another vendor's surface inside this product
Taking an L3 change that breaks L1/L2 contracts Violates the source ladder; the harness regresses
Claiming gates green without running them The whole point of the ledger is that it is auditable
A changelist written from the upstream changelog The owner needs dsb's story, not upstream's release notes
Skipping the ledger because the PR body says it The PR is transient; the ledger is what the next session reads