diff --git a/Forge-and-Tooling.md b/Forge-and-Tooling.md index 5afcc1b..d998253 100644 --- a/Forge-and-Tooling.md +++ b/Forge-and-Tooling.md @@ -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 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. diff --git a/Workflow.md b/Workflow.md index 6d5fdd8..024a8ca 100644 --- a/Workflow.md +++ b/Workflow.md @@ -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