docs(agents): reconcile agent instructions; scope global vs repo #775

Merged

lytedev merged 1 commit from agent-process-reconcile into main

2026-07-17 10:11:45 -05:00

lytedev commented

2026-07-17 04:03:16 -05:00

Owner

Splits agent guidance by scope — global CLAUDE.md = every project, AGENTS.md = this repo/fleet — and fixes what was outright wrong. Docs only; no behavior change.

Stacked on #778. This branch sits on top of the lib/modules/home relocation (#778), so its diff currently shows those file moves too. Merge #778 first, after which this collapses to docs-only. (The global CLAUDE.md now lives at dotfiles/agents/claude/CLAUDE.md, moved by #778.)

Why

Four overlapping sources of truth contradicted each other:

Conflict	Resolution
Workspace path specified two incompatible ways (`~/code/workspaces/nix/<name>` vs in-repo `workspaces/<name>`)	one convention; fetch first + branch off `main@origin` (local `main` goes stale within minutes here)
`jj undo` — listed as a normal command in global, banned in AGENTS.md	banned: it acts on the repo-global op log and can silently revert another agent's push
Commit rewriting — `DEVELOPMENT_WORKFLOW.md` re-described already-pushed changes	that is exactly the divergent-change trap global warns about

Deleted `.claude/DEVELOPMENT_WORKFLOW.md`

Its entire PR flow pointed at lib/modules/home/scripts/agent/bin/pr-submit-and-monitor — a path that no longer exists at all. It also taught in-repo workspaces, pushed-commit rewriting, and --allow-new (removed in jj 0.42). The live path (fj) is already documented in AGENTS.md.

Corrections

Global still pointed at ~/.config/home-manager (gone) → now points at its real source, dotfiles/agents/claude/CLAUDE.md.
fish rules were repo-scoped but are true for every project on this host → moved up to global; only "the remote hosts are fish too" stays here.
Topology refreshed for the 2026-07-09 cutover: beefcake is now the beefcake-blue guest on the battleship hypervisor; deploy .#beefcake ships beefcake-guest; bare-metal nixosConfigurations.beefcake is a fallback that must not be deployed to the box.
Repository-structure section rewritten for the post-#778 layout (no more "dead code" note — nothing in the old lib/modules/home/ was dead).

New: two deploy invariants + a merge policy

A host runs one generation at a time, so "prove it live on prod before merging" forced un-merged branches onto production, where each deploy yanked out whatever the previous agent was still validating. Locking harder only turns simultaneous thrash into sequential thrash.

So state the two things that actually matter:

Never move a host backward unknowingly — already enforced by the deploy guard.
Never clobber in-flight validation — enforced by a host lease (#777); blue/green makes it structural for server workloads.

…and let the merge gate be off-production validation (CI + the beefcake-lite VM gate, a test host, or a green slot) rather than a live prod deploy. Prod-tracks-main stays the recommended default without being a hard requirement.

Also reframed "coordinating with other agents" → "working alongside others on this host": agents aren't asked to coordinate with each other (Daniel orchestrates), just to not clobber — workspace isolation, the secrets/beefcake/secrets.yml hot file (split tracked in new issues/open/split-beefcake-secrets.md), CI cancel-only-superseded.

The stack

#778 — relocate lib/modules/home/ (merge first)
#775 — this (docs reconciliation)
#777 — the deploy host-lease that invariant #2 refers to (independent, off main)

Splits agent guidance by **scope** — global `CLAUDE.md` = every project, `AGENTS.md` = this repo/fleet — and fixes what was outright wrong. Docs only; no behavior change. > **Stacked on #778.** This branch sits on top of the `lib/modules/home` relocation (#778), so its diff currently shows those file moves too. **Merge #778 first**, after which this collapses to docs-only. (The global CLAUDE.md now lives at `dotfiles/agents/claude/CLAUDE.md`, moved by #778.) ## Why Four overlapping sources of truth contradicted each other: | Conflict | Resolution | |---|---| | Workspace path specified two incompatible ways (`~/code/workspaces/nix/<name>` vs in-repo `workspaces/<name>`) | one convention; **fetch first + branch off `main@origin`** (local `main` goes stale within minutes here) | | `jj undo` — listed as a normal command in global, banned in AGENTS.md | **banned**: it acts on the repo-*global* op log and can silently revert another agent's push | | Commit rewriting — `DEVELOPMENT_WORKFLOW.md` re-described already-pushed changes | that is exactly the divergent-change trap global warns about | ## Deleted `.claude/DEVELOPMENT_WORKFLOW.md` Its entire PR flow pointed at `lib/modules/home/scripts/agent/bin/pr-submit-and-monitor` — **a path that no longer exists at all**. It also taught in-repo workspaces, pushed-commit rewriting, and `--allow-new` (removed in jj 0.42). The live path (`fj`) is already documented in AGENTS.md. ## Corrections - Global still pointed at `~/.config/home-manager` (gone) → now points at its real source, `dotfiles/agents/claude/CLAUDE.md`. - **fish** rules were repo-scoped but are true for every project on this host → moved up to global; only "the remote hosts are fish too" stays here. - **Topology refreshed for the 2026-07-09 cutover:** beefcake is now the `beefcake-blue` *guest* on the `battleship` hypervisor; `deploy .#beefcake` ships `beefcake-guest`; bare-metal `nixosConfigurations.beefcake` is a fallback that must not be deployed to the box. - Repository-structure section rewritten for the post-#778 layout (no more "dead code" note — nothing in the old `lib/modules/home/` was dead). ## New: two deploy invariants + a merge policy A host runs **one generation at a time**, so "prove it live on prod before merging" forced un-merged branches onto production, where each deploy yanked out whatever the previous agent was still validating. Locking harder only turns simultaneous thrash into sequential thrash. So state the two things that actually matter: 1. **Never move a host backward unknowingly** — already enforced by the deploy guard. 2. **Never clobber in-flight validation** — enforced by a host lease (#777); blue/green makes it structural for server workloads. …and let the merge gate be **off-production validation** (CI + the `beefcake-lite` VM gate, a test host, or a green slot) rather than a live prod deploy. Prod-tracks-`main` stays the recommended default without being a hard requirement. Also reframed "coordinating with other agents" → **"working alongside others on this host"**: agents aren't asked to coordinate with each other (Daniel orchestrates), just to not clobber — workspace isolation, the `secrets/beefcake/secrets.yml` hot file (split tracked in new `issues/open/split-beefcake-secrets.md`), CI cancel-only-superseded. ## The stack - **#778** — relocate `lib/modules/home/` (merge first) - **#775** — this (docs reconciliation) - **#777** — the deploy host-lease that invariant #2 refers to (independent, off `main`)

lytedev added 1 commit

2026-07-17 04:03:16 -05:00

docs(agents): reconcile agent instructions; scope global vs repo

/ check-format (push) Successful in 11s

Details

/ build (push) Successful in 6m30s

Details

2b46887daf

The agent-facing docs had four overlapping sources of truth that contradicted
each other. Sort every rule by scope — global CLAUDE.md is for what applies to
EVERY project, AGENTS.md for what is specific to this repo and fleet — and fix
what was simply wrong.

Conflicts resolved:

- Workspace convention was specified two incompatible ways: AGENTS.md said
  ~/code/workspaces/nix/<name> (external), .claude/DEVELOPMENT_WORKFLOW.md said
  workspaces/<name> (inside the repo). Keep one, loosely specified.
- jj undo/redo: global listed it as a normal command, AGENTS.md banned it. The
  ban is correct (jj undo acts on the repo-global op log and can silently revert
  another workspace or agent's operation, including a push). Drop it from the
  quick reference, document the hazard, and point at targeted jj edit/abandon/
  restore instead.
- Commit rewriting: DEVELOPMENT_WORKFLOW.md iterated by re-describing an already
  pushed change, which is exactly the divergent-change trap global CLAUDE.md
  warns about.

Deleted .claude/DEVELOPMENT_WORKFLOW.md outright: its entire PR flow pointed at
lib/modules/home/scripts/agent/bin/pr-submit-and-monitor, a path that no longer
exists at all, and its workspace/rewrite guidance was actively harmful. The live
path (fj CLI) is already documented in AGENTS.md.

Corrections:

- lib/modules/home/ was blanket-labelled "dead code, do not edit", but
  lib/modules/home/claude/ is LIVE — it is the source of the global
  ~/.claude/CLAUDE.md, symlinked by lib/modules/nixos/claude.nix. An agent
  following the old text literally would refuse to edit it. Carve it out.
- Global CLAUDE.md still pointed at ~/.config/home-manager, which no longer
  exists; the file lives at lib/modules/home/claude/CLAUDE.md in this repo.
- The fish shell rules were repo-scoped but are true for every project on this
  host, so move the general rules up to global and keep only the remote-hosts-
  are-fish-too specifics here.
- Refresh the beefcake topology for the 2026-07-09 thin-host cutover: beefcake
  is now the beefcake-blue GUEST on the battleship hypervisor, deploy .#beefcake
  ships beefcake-guest, and the bare-metal nixosConfigurations.beefcake survives
  only as a fallback that must not be deployed to the box.

New: the two deploy invariants and a merge policy.

A host runs one generation at a time, so "prove it live on prod before merging"
forced un-merged branches onto production, where each deploy yanked out whatever
the previous agent was still validating. Serializing that only converts
simultaneous thrash into sequential thrash. Instead state the two things that
actually matter — never move a host backward unknowingly (already enforced by
the deploy guard), and never clobber in-flight validation (to be enforced by a
host lock; blue/green makes it structural for server workloads) — and let the
merge gate be off-production validation (CI + the beefcake-lite VM gate, a test
host, or a green slot) rather than a live prod deploy. Prod tracking main stays
the recommended default without being a hard requirement.

The host lock itself lands in a follow-up PR against lib/deploy/guard-wrapper.nix.

lytedev referenced this pull request from a commit

2026-07-17 04:11:26 -05:00

feat(deploy): take a host lease so deploys cannot clobber in-flight validation

lytedev referenced this pull request

2026-07-17 04:12:00 -05:00

feat(deploy): take a host lease so deploys cannot clobber in-flight validation #777

lytedev referenced this pull request from a commit

2026-07-17 10:01:17 -05:00

refactor(modules): relocate lib/modules/home out of the misleading "home" name

lytedev referenced this pull request

2026-07-17 10:01:45 -05:00

refactor(modules): relocate lib/modules/home out of the misleading "home" name #778