Cut every worktree from a freshly fetched origin/main; name the wiki branch

Forge-and-Tooling gets the long form of both facts: a worktree branched
from the local main ref can be many merges behind, and the staleness is
invisible because a subagent's project-instructions block is read from
the spawning session's working directory. Diffs are therefore read
against origin/main, never against main. Both 2026-09-27 measurements
are recorded, including the 105-versus-one-line comparison.

The wiki's own default branch is main, not master — stated where the
clone is described, and again in Workflow next to the fetch-and-rebase
rule, which is where reaching for origin/master actually failed.
jklein committed 2026-09-27 22:58:58 +00:00
1 parent dbe83f9f8f
commit 2c520fae77
2 files changed
+21 -1

No files matched your search

+20
@@ -35,6 +35,24 @@ So a bare `git push` goes to Gitea, the leading copy. The GitHub mirror is fed b
A clone elsewhere may have more than one — the maintainer's machine also carries the mirror, as a remote named `github`. Wherever a second remote exists, say which one you mean, in commands and in prose.
## Cut every worktree from a freshly fetched `origin/main`
```bash
git fetch origin main
git switch -c <branch> origin/main
```
Never from the local `main` ref, and never on the assumption that the shared checkout is current. Both can be many merges behind, and nothing about them says so.
What lifts this above tidiness is how an agent receives its instructions. The **project-instructions block** a subagent is handed at the head of its context — the binding copy of `CLAUDE.md` — is read from the **spawning** session's working directory, not from `origin/main`. A stale worktree therefore presents every agent it starts with rules that were corrected two PRs ago, and the agent cannot tell: a stale block looks exactly as authoritative as a current one.
Measured on 2026-09-27, twice on the same day:
- The manager session's working directory hung several merges back. An agent started from it reported a "contradiction" in `CLAUDE.md` — the remote bullet — that had been fixed two PRs earlier, and quoted the stale text as the rule in force. Nothing broke, because that same agent had checked its diff against `origin/main` instead of against the local pointer.
- In the shared checkout, `main..HEAD` showed **105 differing files**, while the difference against `origin/main` was a single line.
Hence the other half of the rule: **read diffs against `origin/main`, never against `main`.** It is the only comparison here that proves anything. A worktree that turns out to be behind is rebased onto `origin/main` before the work starts, not after — the first thing to run in a fresh worktree is the fetch and the comparison.
## Signed commits are enforced
Branch protection on `main` requires a signature, and signatures verify on Gitea. A commit that is not signed does not reach `main`.
@@ -97,4 +115,6 @@ All of it measured on this instance, not taken from documentation. The full list
git clone ssh://git@git.jk-dev.de:30022/jlab-cluster/helm-charts.wiki.git
```
**Its default branch is `main`, not `master`.** Worth knowing before the first push, because the wiki has no PR flow and every push is preceded by a fetch and a rebase — reach for `origin/master` and the rebase fails. That happened on 2026-09-27; it was harmless, since the push afterwards was a clean fast-forward and no force was involved, but it is avoidable by knowing the name.
Flat layout, one Markdown file per page, `_Sidebar.md` for navigation. Editing it is a required step of the [workflow](Workflow#the-wiki-is-part-of-the-work), not an afterthought.
+1 -1
@@ -51,7 +51,7 @@ git -C helm-charts.wiki push
Page names are file names: `outline.md` is the page `outline`. Links between pages are relative page names without the extension — `[CI/CD](CI-CD)`. `_Sidebar.md` is the navigation shown beside every page; a new page that is not listed there is reachable only by search.
**Fetch and rebase before every push, and never force-push.** The wiki has no PR flow and no review, so two people — or two agents — edit the same page at the same time without noticing: during Gitea #16 and #18 that happened twice within minutes, and only luck made the rebase clean. A force push here deletes the other edit silently, with nothing left to report it.
**Fetch and rebase before every push, and never force-push** — and note that the wiki's default branch is **`main`, not `master`**, so the rebase is onto `origin/main`. The wiki has no PR flow and no review, so two people — or two agents — edit the same page at the same time without noticing: during Gitea #16 and #18 that happened twice within minutes, and only luck made the rebase clean. A force push here deletes the other edit silently, with nothing left to report it.
## Rules for every commit, PR, issue and comment