From cc788d66816f4227209b4db470f845b390c8dbbc Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 16 Jul 2026 21:46:47 +0200 Subject: [PATCH 1/2] docs(git-workflow): guard against basing decisions on a stale worktree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an "A stale worktree is a stale source" subsection: before deciding from what a repo contains (dependency constraints, whether a fix is on main, a signature to code against), read origin/main or a fresh worktree — not the stale checkout. Covers reporting a stale value as fact, subagents reading a stale tree, and verifying a dependency signature at the resolved version. Signed-off-by: Sebastian Mendel --- .../git-workflow/references/advanced-git.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/skills/git-workflow/references/advanced-git.md b/skills/git-workflow/references/advanced-git.md index 4cdcbaa..f8b3924 100644 --- a/skills/git-workflow/references/advanced-git.md +++ b/skills/git-workflow/references/advanced-git.md @@ -341,6 +341,35 @@ git worktree remove ../project-feature git worktree prune ``` +### A stale worktree is a stale source + +A worktree checked out days ago can be many commits behind `origin` — its +`composer.json`, its "what's on `main`", its API signatures are all whatever they +were at that checkout, not now. Before basing a **decision** on what a repo +contains — a dependency version constraint, whether a fix already landed on +`main`, a class/method signature you're about to code against — read the *current* +state, not the stale worktree: + +```bash +git fetch origin && git -C log --oneline origin/main -3 # or: +git worktree add ../fresh origin/main # read from a fresh tree +``` + +Two recurring failure modes: + +- **Reporting a stale value as fact.** Reading `"^0.13"` from an un-fetched + worktree and stating "the constraint needs bumping" — when current `main` already + says `"^0.17 || ^0.18 || ^0.19"`. Verify against `origin/main` before writing the + claim into a design or PR. +- **A subagent silently reads a stale checkout.** When you dispatch an agent to + "read the source" for a decision, name the ref/worktree it must read, and + re-verify its structural claims (config keys, signatures) against the current + tree before building on them — half a report can come from an outdated path. + +Confirm the constructor/signature at the **resolved** dependency version (the one +installed in `vendor`/`.Build`), not the library's `main` branch — they drift +(e.g. a value object gaining a required constructor arg between minor releases). + ### Bare-Repo Layouts With the bare-clone convention (`project/.bare` + one directory per branch), From 0d01232d283d60d8d267d83a40a15fdfd3dc5f11 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 16 Jul 2026 22:26:19 +0200 Subject: [PATCH 2/2] docs(git-workflow): scope fetch with -C (review) Signed-off-by: Sebastian Mendel --- skills/git-workflow/references/advanced-git.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/git-workflow/references/advanced-git.md b/skills/git-workflow/references/advanced-git.md index f8b3924..02220d3 100644 --- a/skills/git-workflow/references/advanced-git.md +++ b/skills/git-workflow/references/advanced-git.md @@ -351,8 +351,8 @@ contains — a dependency version constraint, whether a fix already landed on state, not the stale worktree: ```bash -git fetch origin && git -C log --oneline origin/main -3 # or: -git worktree add ../fresh origin/main # read from a fresh tree +git -C fetch origin && git -C log --oneline origin/main -3 # or: +git worktree add ../fresh origin/main # read from a fresh tree ``` Two recurring failure modes: