docs(upstream): how we take changes from upstream now the fork link is gone

[diffwireauto]

Adds docs/UPSTREAM.md, the policy that replaces the fork button, and references it from AGENTS.md.

CoreScope left the Kpa-clawbot fork network on 2026-10-03 (#158, #161). There is no Sync fork button and no automatic path for upstream code to arrive. That is deliberate — the last batch sync was 583 files, 100+ commits, 20 authors in one PR, and it carried a config-contract break that blanked the prod map (#156). This documents how a wanted upstream change gets taken one at a time instead.

Two commits: 0c696c49 drafted it, 9ce3b410 fixes what an adversarial review found.

What it settles

#163 asked for	where
Mechanism	upstream as a read-only remote, cherry-pick -x per change, never per batch
Review checklist	8 items, the #156 config-field class first because nothing in CI can catch it
Attribution	cherry-pick preserves the original author; a squashed reimplementation silently reassigns credit
What we never take	#144's agent surface, as a principle with examples rather than a denylist

What it does not settle, on purpose

Cadence. Who reads upstream and how often is an owner and team decision, not a session's. The document says so plainly, and says what "on demand" costs: an upstream security or crash fix can sit unnoticed until it bites us, against a measured ~88 commits / 4 releases per 30 days.

Split to #184 under the same epic so the policy could land without being held hostage to it.

What the review changed

Gemini 2.5 Pro, prompted adversarially against #163's five requirements. It found real defects, not wording:

Wrong or unusable as written

• The worktree command hardcoded a Windows absolute path and fails anywhere else. Now $WORKTREES, with a note to set it.
• Checklist item 1 — the config check that exists because of bug: upstream sync moved the Carto key to a new config field, breaking map tiles (dev now, prod on next deploy) #156 — told the reader to compare against live config and then pointed at a private repo, dead-ending anyone without access. Now gives a runnable alternative (/api/config/client reports the effective config including filled-in defaults) and says plainly that without box or instance access you cannot complete the item and must hand it off rather than skip it.

False confidence

• The upstream-ref grep was presented as proof. It only finds the name spelled out literally; a path assembled at runtime passes it. That is exactly how bug(ci): release-fast-path verifies and deletes against ghcr.io/kpa-clawbot, not our registry #164 survived ten weeks — the value was written four times and only two were changed. Now says to read how the change builds repo and registry strings.
• The never-take list read as a denylist someone would check instead of thinking. Now explicitly subordinate to the question "is this a file that tells an agent how to behave, that we did not write?", with unlisted cases named (.prompts/, docs/ai/, .cursor/, CLAUDE.md).
• Conflict guidance said "resolve by hand" without saying how to learn why our side looks the way it does. Adds git log -L / -S and says to ask whoever owns the local change rather than guess, because a hand-resolved conflict that quietly drops one of our fixes is worse than a pick we declined.

Missing entirely

• No rollback. The document was purely preventative, and prevention already failed once — bug: upstream sync moved the Carto key to a new config field, breaking map tiles (dev now, prod on next deploy) #156 reached prod. Adds reverting a pick, finding taken commits via -x, and that redeploying the previous tag beats a revert when prod is affected.
• No guidance for a multi-commit change, which invited exactly the batch sync this policy exists to prevent. Adds the range pick and the test for when something has stopped being a change and become a batch.
• Dependency item 4 listed commands but no criteria, so it could not produce a decision. Adds what blocks a pick (a reachable vulnerability, a copyleft licence), what is the owner's call (a new direct dependency), and what merely gets noted.

Claims verified rather than asserted

• 88 commits in 30 days against 4 releases [api: repos/Kpa-clawbot/CoreScope, 2026-10-07]
• the required-status-check command in item 2 returns ✅ Go Build & Test, which is the emoji-in-context hazard it warns about
• AGENTS.md:5 carries the reference, satisfying task: how we track upstream after the fork link is gone #163's done-when
• the reviewer tool path is scripts/llm-consult.py, installed by preflight.sh §5b. An earlier edit in this branch changed it to a stale legacy copy; 9ce3b410 puts it back.

Scope

Docs only. No code, no CI, no config. #163 is closed; Epic #158 stays open.

Refs #163, #184, #158, #156, #164

[diffwireauto]

Human approval received from Ben in session 64287058 ("Merge #185."). Re-validated against the remote immediately prior: 2 commits, 2 files (AGENTS.md, docs/UPSTREAM.md), mergeable=MERGEABLE.

Rebased onto current master before merging rather than merging BEHIND: the ruleset carries strict_required_status_checks_policy: true, so an out-of-date branch would have needed an admin override of the status-check requirement instead of satisfying it. New head 57a4621d4f27e93b3ef103cf29fbadf9d6796792; scope unchanged by the rebase. CI re-running against the rebased head.