docs: cut every worktree from a freshly fetched origin/main
Validate Helm Charts / Detect changed charts (pull_request) Successful in 3s
Validate Helm Charts / Build ${{ fromJSON(needs.detect-changed-charts.outputs.charts) }} (pull_request) Skipped
Validate Helm Charts / Trivy config ${{ fromJSON(needs.detect-changed-charts.outputs.scan-charts) }} (pull_request) Skipped
Validate Helm Charts / Install-test (pull_request) Skipped
Validate Helm Charts / Resource quantities (pull_request) Successful in 8s

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
This commit is contained in:
jklein committed 2026-09-27 22:58:39 +00:00
1 parent 5c513291a8
commit 56bed94064
1 file changed
+3
+3
View File
@@ -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.