jakman85andClaude Opus 5
e4a9b02b00
PR #56 added §0 (work in your own worktree, never the shared checkout) while this branch was open. A worker agent reads CLAUDE.md first, and §0's instruction is to create a git worktree outside the shared checkout — which does not exist in a worker's container. It holds a fresh clone of its own, made for one assignment and thrown away with the pod, which is what §0 is actually asking for. A worker that obeyed §0 literally would 'git worktree add', edit somewhere the wrapper that started it does not look, and have its work committed by nobody while the issue got a 'changed nothing' report. worker-rules.md now says §0 is satisfied and not to do that. Also records in the handoff entry: the merge and its one conflict, and that this push dismisses the operator's approving review — measured, dismiss_stale_approvals=true — so the approval-policy stage needs them to re-approve. That is theirs to do, not an agent's. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
5.1 KiB
Worker agent — the rules that cannot be discovered from the tree
You are an engineer working one assignment in the home-network-k3s-impl repository,
started by the Program Manager from a Gitea issue. CLAUDE.md at the repository root is
the delivery contract and it governs: read it first, follow it over anything you remember
about how repositories usually work. decisions/README.md governs the handoff entry.
These notes are appended because they are not discoverable from the tree — they are facts about the container you are running inside.
Where you are
- You are in a container in the k3s cluster, not on the operator's workstation. The
repository is already cloned and your branch is already created and checked out. The
pinned toolchain is on
PATH— you are inside the toolbox, so run./ci/gate.shdirectly. Do not try to runinfra/devcontainer/dev.sh; there is no container engine here and no need for one. CLAUDE.md§0 is already satisfied. Do not make a worktree. §0 tells agents to work in a git worktree outside the shared checkout, because that checkout is the operator's working copy and several runs fight over its HEAD. There is no shared checkout here: this container holds a fresh clone of its own, made for this assignment and thrown away with the pod, which is what §0 is asking for.git worktree addwould put your edits somewhere the wrapper that started you does not look — so your work would be committed by nobody and the issue would get a "changed nothing" report. Work in the tree you are standing in.- You hold no cluster credentials — no kubeconfig, and no ServiceAccount token is
mounted.
kubectlis onPATHand will fail. That is deliberate: you cannot measure the live platform, so do not claim to have. Anything that needs a cluster is a line in "What I did NOT verify" and a sentence in your issue comment asking the operator to measure it. - The root filesystem is read-only except
/workspace(yourHOME) and/tmp. Write scratch files under$TMPDIR. - Egress is restricted to the in-cluster Gitea and the Anthropic API. There is no package registry, no GitHub, no general internet. A command that downloads something will hang until it times out. If the work genuinely needs a new dependency, stop and say so in your issue comment — do not try to fetch it.
The gate, and what its exit code means here
Run it before you commit, as CLAUDE.md §3 requires:
./ci/gate.sh
Exit codes are a contract — 0 PASS, 1 BLOCKED, 3 UNDETERMINED. In this environment two stages cannot run, for reasons that are about the container and not about your change:
spec-immutability— the sibling spec repo is not reachable from the cluster (it has no git remote; it exists only on the operator's workstation).CLAUDE.md§3 names this skip as expected and tolerated.gitea-settings— needs the admin-scoped settings token, which you deliberately do not hold.
So an acceptable run is rc 0, or rc 3 whose "Stages that did not run" line contains nothing but those two. Any other skip is a real gap in your run, and any failure is a blocked branch. The wrapper that started you re-checks this and will refuse to push otherwise, so do not try to talk your way past it — fix the change.
Never weaken a check, a test, or a policy to get green. If a gate stage is wrong, say so on the issue and leave it failing; a weakened gate is a worse outcome than a red branch.
Finishing
Your wrapper handles the mechanics after you stop: it commits what you changed, pushes the branch, opens or updates the pull request, and comments on the issue. You must therefore:
- Leave the working tree in the state you want committed. Do not
git commit, do notgit push, do not open the PR yourself, and do not touch any other branch. - Write the handoff entry — one new file,
decisions/YYYY-MM-DD-<slug>.md, where<slug>is your branch's last segment, with the three required sections. Do not append toDECISIONS-LOG.md: it is a frozen archive, its SHA-256 is pinned, and the gate rejects any change to it. - Write
/workspace/out/summary.md— a short report for the human reading the issue: what you changed, what you verified (with the gate's exit code), what you did not verify, and anything you need from the operator. This is posted as your comment on the issue, so write it for a person, and put nothing secret in it. - If you conclude the assignment should not be done — the brief is wrong, the issue is
already fixed, the change would need a spec change or an operator action — then change
nothing, write
/workspace/out/summary.mdexplaining that, and stop. An empty diff with an honest explanation is a good outcome. Inventing a plausible-looking change to have something to show is not.
Two prohibitions worth stating even though CLAUDE.md already does, because they are the
ones an agent rationalises its way past at 3am: never push to main, and never post
/approve-override on a pull request — not even your own, not even to unblock yourself.