diff --git a/.claude/rules/agent-worktree-hygiene-never-hold-main-never-step-on-operator-cleanup-on-pr-merge.md b/.claude/rules/agent-worktree-hygiene-never-hold-main-never-step-on-operator-cleanup-on-pr-merge.md index a8d117889d..1a6a19d357 100644 --- a/.claude/rules/agent-worktree-hygiene-never-hold-main-never-step-on-operator-cleanup-on-pr-merge.md +++ b/.claude/rules/agent-worktree-hygiene-never-hold-main-never-step-on-operator-cleanup-on-pr-merge.md @@ -169,18 +169,18 @@ operator MAY have `main` checked out in their own primary, but agents must not. ```bash -# Should print no lines. If any line prints, an agent worktree is -# holding [main] and is the blocker for operator git operations. +# Prints OK on success. If a worktree line prints, an agent worktree +# is holding [main] and is the blocker for operator git operations. git worktree list | awk '/\[main\]/ { path=$1 } END { exit 0 }' \ && git worktree list | grep -E "\[main\]" \ | grep -E "/private/tmp/zeta-|/tmp/zeta-" || echo "OK: no agent holds [main]" ``` -Expected result: no agent worktree holds `[main]`. No output is OK when the -operator's primary checkout is not currently on `main`; a single operator -primary line is also OK when the operator intentionally has `main` checked out. -Any `/private/tmp/zeta-*`, `/tmp/zeta-*`, or per-agent worktree line holding -`[main]` is a violation to fix. +Expected result: `OK: no agent holds [main]`, or equivalently no +agent-worktree match if the final echo is omitted. A single operator +primary line is OK when the operator intentionally has `main` checked +out. Any `/private/tmp/zeta-*`, `/tmp/zeta-*`, or per-agent worktree +line holding `[main]` is a violation to fix. ## Substrate-honest framing @@ -206,11 +206,10 @@ worktrees in the operator's primary checkout subdir (peer-agent prefix; from past work), and 1 stale `/private/tmp/zeta--2` worktree holding `[main]` at stale SHA. -The `[main]`-holding worktree was THE blocker for operator's -`git checkout main` in primary checkout. Operator explicit: *"i'm -stuck (max)... fatal: 'main' is already used by worktree at -'/private/tmp/zeta--2'... nope we need to fix this mess -yall always stepping on each other and me constantly"*. +The `[main]`-holding worktree was THE blocker for the operator's +`git checkout main` in the primary checkout. The exact operator quote +is preserved on the B-0750 backlog/history surface; this current-state +rule keeps the operational lesson in role-reference form. Mass-cleanup (37 worktrees removed) plus this rule landing prevents recurrence. Future agent surfaces inherit the discipline at cold-boot. diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 0d3d9379d6..f1264563db 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -697,7 +697,7 @@ are closed (status: closed in frontmatter)._ - [ ] **[B-0737](backlog/P2/B-0737-zflash-touch-id-pam-plus-short-challenge-format-plus-iso-auto-discovery-i-execute-you-fingerprint-aaron-2026-05-25.md)** zflash — "I execute, you fingerprint" — Touch ID PAM as the irreversible-action consent gate + short `yes <4-hex>` challenge + ISO auto-discovery (~14 keystrokes total for human; agent-driven path uses same Touch ID floor) - [ ] **[B-0742](backlog/P2/B-0742-reference-k8s-local-stack-as-aces-distributable-poc-hats-as-negotiated-fork-structure-on-top-deterministic-declarative-gitops-ai-native-human-native-aaron-2026-05-25.md)** Reference k8s local stack in Zeta as Ace's distributable PoC — hats become the negotiated fork structure ON TOP of the reference stack — anyone can use it, anyone can negotiate back hats + new cluster primitives + new charts via the B-0741 ontology negotiation protocol — Ace's PoC of reliable AI control over all package managers in a deterministic + declarative / desired-state / GitOps-friendly + AI-native + human-native way - [ ] **[B-0748](backlog/P2/B-0748-kro-crossplane-koreo-kubevela-carvel-ack-kcc-aso-spectrum-evaluation-for-zeta-reference-stack-machine-state-fork-state-aaron-2026-05-25.md)** kro + Crossplane + Koreo + KubeVela + Carvel + ACK/KCC/ASO spectrum evaluation for Zeta — adopt where it composes (Aaron 2026-05-25 'kro yes' endorsement + 'we need lots of research in this area and backlog' direction); evaluate adoption against B-0742 reference stack + B-0747 machine-state reconciler + B-0741 cross-cluster federation + downstream-fork story -- [ ] **[B-0750](backlog/P2/B-0750-agent-worktree-hygiene-rule-landing-plus-mechanization-target-cleanup-tooling-plus-worktree-pool-primitive-aaron-2026-05-25.md)** Agent worktree hygiene — rule-landing + substrate-engineering mechanization target — periodic cleanup tooling + worktree-pool handoff to B-0558/B-0751; operator's 'we need to fix this mess yall always stepping on each other and me constantly' anchor 2026-05-25 (37 worktrees mass-cleaned + rule landed simultaneously) +- [ ] **[B-0750](backlog/P2/B-0750-agent-worktree-hygiene-rule-landing-plus-mechanization-target-cleanup-tooling-plus-worktree-pool-primitive-aaron-2026-05-25.md)** Agent worktree hygiene — rule-landing + substrate-engineering mechanization target — periodic cleanup tooling + worktree-pool handoff to B-0558 plus PR #5019 clone-architecture sibling; operator's 'we need to fix this mess yall always stepping on each other and me constantly' anchor 2026-05-25 (37 worktrees mass-cleaned + rule landed simultaneously) - [ ] **[B-0752](backlog/P2/B-0752-fighting-past-self-vs-peer-distinguisher-rule-landing-plus-identity-tagging-mechanization-aaron-vera-2026-05-25.md)** Fighting past-self vs peer-agent — distinguisher rule landing + identity-tagging mechanization scope (Aaron 2026-05-25 'you don't do like vera and just leave it unfixed cause you assume it's someone elses issues') - [ ] **[B-0755](backlog/P2/B-0755-cluster-role-taxonomy-expansion-control-plane-gpu-worker-cpu-worker-storage-all-in-one-aaron-2026-05-25.md)** Cluster role taxonomy expansion — control-plane-gpu, worker-cpu, worker-storage, all-in-one fused host configs - [ ] **[B-0759](backlog/P2/B-0759-cluster-install-ux-audit-against-first-time-cli-user-persona-easier-than-proxmox-3-node-production-ready-aaron-2026-05-25.md)** Cluster-install UX audit against first-time-CLI-user persona — "easier than Proxmox" bar + 3-node production-ready inflection diff --git a/docs/backlog/P2/B-0750-agent-worktree-hygiene-rule-landing-plus-mechanization-target-cleanup-tooling-plus-worktree-pool-primitive-aaron-2026-05-25.md b/docs/backlog/P2/B-0750-agent-worktree-hygiene-rule-landing-plus-mechanization-target-cleanup-tooling-plus-worktree-pool-primitive-aaron-2026-05-25.md index 76de661ec6..fa831ee8c8 100644 --- a/docs/backlog/P2/B-0750-agent-worktree-hygiene-rule-landing-plus-mechanization-target-cleanup-tooling-plus-worktree-pool-primitive-aaron-2026-05-25.md +++ b/docs/backlog/P2/B-0750-agent-worktree-hygiene-rule-landing-plus-mechanization-target-cleanup-tooling-plus-worktree-pool-primitive-aaron-2026-05-25.md @@ -4,14 +4,13 @@ priority: P2 status: open created: 2026-05-25 last_updated: 2026-05-26 -title: Agent worktree hygiene — rule-landing + substrate-engineering mechanization target — periodic cleanup tooling + worktree-pool handoff to B-0558/B-0751; operator's 'we need to fix this mess yall always stepping on each other and me constantly' anchor 2026-05-25 (37 worktrees mass-cleaned + rule landed simultaneously) +title: Agent worktree hygiene — rule-landing + substrate-engineering mechanization target — periodic cleanup tooling + worktree-pool handoff to B-0558 plus PR #5019 clone-architecture sibling; operator's 'we need to fix this mess yall always stepping on each other and me constantly' anchor 2026-05-25 (37 worktrees mass-cleaned + rule landed simultaneously) domain: ops-tooling ferried_by: aaron owners: [aaron] composes_with: - B-0530 - B-0558 - - B-0751 related_substrate: - .claude/rules/agent-worktree-hygiene-never-hold-main-never-step-on-operator-cleanup-on-pr-merge.md - .claude/rules/claim-acquire-before-worktree-work.md @@ -22,7 +21,7 @@ tags: [agent-worktree-hygiene, multi-agent-worktree-contention, operator-unblock ## Carved blade -> Operator 2026-05-25: *"i'm stuck (max) ➜ Zeta git:(lior-archive-prs-2026-05-26) ✗ git checkout main → fatal: 'main' is already used by worktree at '/private/tmp/zeta-riven-loop-2'... nope we need to fix this mess yall always stepping on each other and me constantly."* The proximate cause was 37 agent worktrees from one substrate-cascade day, including one peer-agent worktree holding `[main]` at stale SHA. Mass-cleanup unblocked + the agent-worktree-hygiene rule landed simultaneously, but the substrate-engineering target is mechanization: periodic cleanup tooling (auto-prune post-PR-merge) plus an ownership architecture handoff. The older worktree-pool primitive remains in B-0558; B-0751 (PR #5019, per-agent isolated clones) supersedes the pool as the preferred architecture for future agent isolation. Until mechanization lands, agent-side compliance with the rule operates the discipline. +> Operator 2026-05-25: *"i'm stuck (max) ➜ Zeta git:(lior-archive-prs-2026-05-26) ✗ git checkout main → fatal: 'main' is already used by worktree at '/private/tmp/zeta-riven-loop-2'... nope we need to fix this mess yall always stepping on each other and me constantly."* The proximate cause was 37 agent worktrees from one substrate-cascade day, including one peer-agent worktree holding `[main]` at stale SHA. Mass-cleanup unblocked + the agent-worktree-hygiene rule landed simultaneously, but the substrate-engineering target is mechanization: periodic cleanup tooling (auto-prune post-PR-merge) plus an ownership architecture handoff. The older worktree-pool primitive remains in B-0558; the per-agent isolated-clones architecture in PR #5019 supersedes the pool as the preferred architecture for future agent isolation, but is not listed in `composes_with` until its backlog row is main-visible. Until mechanization lands, agent-side compliance with the rule operates the discipline. ## Origin @@ -58,19 +57,21 @@ Plus specific cleanup commands (audit / per-worktree clean check / mass-remove s - Composes with B-0530 cron-sentinel mutex semantics - Acceptance: tool exists; runs successfully; at least one cycle of auto-cleanup demonstrated -### Scope item 2 — Worktree-pool primitive handoff (B-0558 + B-0751) +### Scope item 2 — Worktree-pool primitive handoff (B-0558 + PR #5019) - B-0558 already owns the original worktree-pool primitive (pre-allocated sideticks per Otto identity; PR #3894 archive: `docs/pr-discussions/PR-3894-backlog-b-0558-worktree-pool-primitive-re-land-of-3817-backl.md`) -- B-0751 (PR #5019, per-agent isolated clones) supersedes a shared - worktree pool as the preferred architecture for per-agent isolation +- PR #5019 (per-agent isolated clones architecture) supersedes a + shared worktree pool as the preferred architecture for per-agent + isolation. It is referenced by PR URL/number here, not frontmatter + `composes_with`, because its backlog row is not yet main-visible. - This B-0750 row therefore tracks only the hygiene delta: agents must not hold `main`, must not use operator paths, and must clean up owned worktrees after merge/abandon - Any future pool work should compose through B-0558 or be explicitly - deferred under B-0751 clone architecture; B-0750 should not grow a - second pool implementation track + deferred under the PR #5019 clone architecture; B-0750 should not + grow a second pool implementation track ### Scope item 3 — Post-PR-merge auto-cleanup hook @@ -98,7 +99,7 @@ Plus specific cleanup commands (audit / per-worktree clean check / mass-remove s - **Cross-machine agent worktree coordination** — if agents run on different machines + share git via push/pull, the worktrees are per-machine; cross-machine cleanup is future scope - **New worktree-pool implementation** — B-0558 owns the historical - pool primitive; B-0751 per-agent clones supersede the shared-pool + pool primitive; PR #5019 per-agent clones supersede the shared-pool approach for new architecture work - **Operator's own worktree creation** — operator can always create worktrees anywhere; rule applies to agents only - **Automated branch deletion** — separate scope; depends on PR-mergedness + downstream dependencies (per B-0741 fork interop) @@ -117,8 +118,9 @@ Plus specific cleanup commands (audit / per-worktree clean check / mass-remove s - **B-0530** (cron-sentinel mutex; existing partial substrate) — same problem class at runtime scope; this row's cleanup discipline composes - **B-0558** (worktree-pool primitive per Otto identity) — owns the historical pool design; B-0750 narrows to hygiene + cleanup delta -- **B-0751** (per-agent isolated clones; PR #5019) — supersedes shared - pool direction as the preferred isolation architecture +- **PR #5019** (per-agent isolated clones) — supersedes shared pool + direction as the preferred isolation architecture; intentionally not + in `composes_with` until its B-row exists on main - **B-0732** (leverage-class safety substrate) — Layer 1 provenance chain captures cleanup events - **B-0737** (zflash empirical anchor) — operator was trying to use zflash when the worktree mess blocked them; concrete pain - **B-0746** (GitHub force-push lesson) — related sibling failure mode at GitHub-state scope