docs: lock in fork stance, reframe cherry-pick list as reference-only

After attempting cluster B (4 surgical agent-session fixes), even the
first commit conflicted because of structural namespace divergence
(gsd_*→sf_* rename, @sf-run/*→@singularity-forge/* rename, prior
pi-mono direct cherry-picks). The conflicts are real semantic
divergence, not noise.

Conclusion: sf is a fork; we do not periodically sync from
gsd-build/gsd-2. Pretending we still track upstream means weeks of
merge work for diminishing return.

BUILD_PLAN.md adds an explicit "Upstream stance" section documenting
the fork posture and the rationale for the three irreversible naming
choices.

UPSTREAM_CHERRY_PICK_CANDIDATES.md is reframed as a reference list,
not an action plan. The clusters and SHAs remain useful as an
intelligence source — port specific fixes by hand when one bites us;
do not run automated cherry-picks against the list.

Pi-mono SDK syncs continue separately — that path doesn't have the
same divergence problem.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

BUILD_PLAN.md

@@ -8,6 +8,26 @@ It is opinionated. Each item has a tier and a one-line rationale. Reorder freely
 
 ---
 
+## Upstream stance
+
+**sf is a fork.** We do not periodically sync from `gsd-build/gsd-2`.
+
+We tried (see attempt log in `UPSTREAM_CHERRY_PICK_CANDIDATES.md`). The conflicts run deep because of three structural choices that are intentional and won't be reverted:
+
+- We renamed `gsd_*` tool names → `sf_*` (`421fccd89`).
+- We renamed `@sf-run/*` → `@singularity-forge/*` package scope (`f92ee8d64`).
+- We've cherry-picked tool fixes from `pi-mono` upstream directly (`f153521c2`), which addresses some bugs that `gsd-2` fixed differently.
+
+Pretending we still track gsd-2 means weeks of merge work for diminishing return. Better to:
+
+- **Treat `gsd-build/gsd-2` upstream as an intelligence source.** We read it. We hand-port fixes when one specifically bites us. `UPSTREAM_CHERRY_PICK_CANDIDATES.md` is a reference list of what's available, not an action plan.
+- **Pull from `pi-mono` directly for SDK improvements.** We've already been doing this; continue.
+- **Track our own roadmap** via `SPEC.md` and this file.
+
+If a specific upstream fix matters (e.g. a CVE, a bug we hit), port it manually and credit upstream in the commit message. Don't try to sync the whole tree.
+
+---
+
 ## Tier 1 — ESSENTIAL (block v3 ship)
 
 These resolve real product or correctness gaps. v3 isn't v3 without them.

UPSTREAM_CHERRY_PICK_CANDIDATES.md

@@ -1,10 +1,14 @@
-# Upstream cherry-pick candidates
+# Upstream reference list (NOT a cherry-pick action plan)
 
-A read-only enumeration of high-value commits in `gsd-build/gsd-2` (`upstream/main` at `fec206dda`, 2026-04-28) that are not in `singularity-ng/singularity-foundry/main` (at `b24f426f2`, 2026-04-29).
+> **Status: REFERENCE.** sf is a fork; we do not sync from `gsd-build/gsd-2`. See [`BUILD_PLAN.md`](./BUILD_PLAN.md) §"Upstream stance" for why. This file is preserved as **an intelligence list** — high-value upstream work to read or hand-port if a specific bug or feature warrants it. Do not run `git cherry-pick` against this list; the rename divergence (`gsd_*`→`sf_*`, `@sf-run/*`→`@singularity-forge/*`, partial pi-mono cherry-picks) makes automated picks conflict on virtually every commit.
+>
+> **An attempt was made and rolled back:** cluster B's first commit conflicted on `agent-session.ts` and a deleted test file. Aborted clean. The conflicts were semantic (real divergence), not whitespace.
 
-Total upstream-only commits: 4,589. This list is the **high-leverage subset** worth cherry-picking. Skipping the bulk of small/internal commits.
+A read-only enumeration of notable commits in `gsd-build/gsd-2` (`upstream/main` at `fec206dda`, 2026-04-28) that are not in `singularity-ng/singularity-foundry/main` (at `b24f426f2`, 2026-04-29).
 
-Clusters are roughly ordered by "take this first." Each cluster lists candidate SHAs with one-line context.
+Total upstream-only commits: 4,589. This list is the **high-leverage subset** worth being aware of. Skipping the bulk of small/internal commits.
+
+Clusters are roughly ordered by "if any port is worth doing, this first." Each cluster lists SHAs with one-line context.
 
 ---