From 56bed9406430c5774dc89fcef7511afe09be071b Mon Sep 17 00:00:00 2001 From: Justin Klein Date: Sun, 27 Sep 2026 22:58:39 +0000 Subject: [PATCH] docs: cut every worktree from a freshly fetched origin/main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A worktree branched from the local main ref can be arbitrarily old, and the staleness is invisible where it costs most: the project-instructions block a subagent receives at the head of its context is read from the spawning session's working directory, not from origin/main. An outdated worktree therefore hands every agent rules that were already corrected. Measured on 2026-09-27: an agent reported a contradiction in CLAUDE.md that two PRs had already fixed, and quoted the stale copy as binding. Nothing broke only because the same agent compared its diff against origin/main rather than against the local pointer. The same day, in the shared checkout, main..HEAD showed 105 differing files while the difference against origin/main was one line. Also name the wiki's default branch: it is main, not master. Since the rule to fetch and rebase before every wiki push, the name is required — an agent tried to rebase onto origin/master and the rebase failed. Fixes #57 --- CLAUDE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 531ddf8..404e5f7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,6 +29,8 @@ The knowledge base is the Gitea wiki at `https://git.jk-dev.de/jlab-cluster/helm git clone ssh://git@git.jk-dev.de:30022/jlab-cluster/helm-charts.wiki.git ``` +Its default branch is `main`, not `master`. + Flat layout, one Markdown file per page, page name = file name, links are relative page names without the extension (`[CI/CD](CI-CD)`). A new page must also be listed in `_Sidebar.md`, or it is reachable only by search. **There is no PR flow here, so fetch and rebase before every push and never force-push** — two agents have already edited the same page minutes apart, and a force push deletes the other edit silently, with nothing left to report it. @@ -56,6 +58,7 @@ Everything runs on the Gitea instance JLab-Git: issues, pull requests, CI and Re - **`tea`, not `gh`.** Work happens in a **Coder workspace, and it has no `op`** — that is the normal case here, not a broken environment, so do not wait for the 1Password CLI or propose installing it. Call `tea` directly; it carries the workspace's stored login and opens PRs and issues under the **bot account**, which is accepted. Say so in the report when something is authored that way. (`op plugin run -- tea`, the older instruction, applies only where `op` actually exists.) - **The remote is `origin`, and it points at Gitea** (`ssh://git@git.jk-dev.de:30022/jlab-cluster/helm-charts.git`). The checkout has exactly that one, and so does every worktree cut from it, so a bare `git push` goes to the leading copy; the github.com mirror is fed by Gitea itself and is never pushed to by hand. A clone elsewhere may carry the mirror as a second remote named `github` — wherever more than one exists, say which one you mean. +- **Cut every worktree from a freshly fetched `origin/main`.** `git fetch origin main` first, then branch from `origin/main` — never from the local `main` ref, and never assume the shared checkout is current: both can be many merges behind. The staleness is invisible where it matters most, because the project-instructions block a subagent receives is read from the **spawning** session's working directory, so an outdated worktree hands every agent rules that were corrected two PRs ago. Measured on 2026-09-27: an agent reported a contradiction in this file that had been fixed two PRs earlier, quoting the stale copy as binding. For the same reason, check a diff against `origin/main`, never against `main`. - **Branch protection with a signature requirement is active**, and signatures verify on Gitea. A commit that is not signed does not reach `main` — check before opening a PR, do not discover it at merge time. - **No merge queue.** Gitea has none, and its place is taken by **auto-merge on green checks**: the PR is armed once and merges itself when the required check passes **and the required review exists** — both are active on `main`, so an armed PR without a review sits there instead of merging. Rule 7 above is unchanged — the user merges, and an agent never merges its own PR or arms auto-merge on it. - **A required check per chart is not possible.** Gitea runs a whole matrix as one job under one status context, so the install-test reports once for all charts. What is required on `main` is `validate-charts`, as that single context; per chart is the part that cannot be had. Relevant whenever branch protection is touched.