naudachu
8b1b11001a
The plugin and the binary shipped on two release cadences and nothing on an operator's machine ever checked that the one they installed described the other. The generated flag block existed precisely so a renamed flag could not ship with documentation recommending the old one — and then shipped one version behind the registry it came from, which is the same bug one hop downstream. So the prose moved into the binary. `internal/scaffold` embeds every document; `kettle init` and `kettle gen scaffold` write them into a project's own `.claude/`. The two cannot disagree because there is one artefact. The namespace survived the move. A project's skills are flat, so the prefix is spelled into the directory name (`kettle-issue`); a project's *commands* take their namespace from a subdirectory, so `commands/kettle/init.md` is still `/kettle:init`. Four of the six command files are thin pointers at a skill, and that is what kept ~1,600 lines of `/kettle:…` cross-references true without a rewrite. `init` and `auth` lost `disable-model-invocation: true` — being a command is that property — and `auth` now restricts `allowed-tools` so a model cannot reach `kettle auth add` at all. `gen scaffold` writes files whole rather than splicing a region. The old refusal protected somebody's hand-written prose around the block; that prose is embedded now, so there is none to protect, and preserving local edits would freeze a project's documentation at whatever version first initialized it. `--check` warns before an upgrade discards one. The plugin's `agents-sync.sh` — 141 lines of Python behind a filename that said `.sh` — became `internal/mirror` and `kettle mirror`. Same seven branches, same refusal to merge two real files that differ, now with a table test per branch and a check that a repair converges in one pass. `--hook` is the PreToolUse form and exits 0 on every path including a panic. It is opt-in per project, which is strictly narrower than the plugin hook that was on for everybody who installed it. `kettle init --interactive` walks a person through the login, the token (read with the echo off, so it lands in no history and no file), the repository, the `.claude/` tree and the mirror hook. It refuses a stdin that is not a terminal and names the flags instead: every question it asks has one, and it performs nothing itself, so an interactive run and a flag run are one code path. Two rules that used to be prose are now the binary's: init refuses a linked worktree and names the main checkout, and writing into an existing `.claude/settings.json` is refused with the snippet printed rather than reformatting a file the operator commits. The scaffold version stamp went to its own `.kettle/scaffold.yaml` rather than into `config.yaml`, because unknown keys there are a hard error and that file may be committed and read by whatever build each machine has. golang.org/x/term becomes a direct dependency; it was already in the tree indirectly, so no module was added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.6 KiB
AGENTS.md — internal/mirror
One filesystem invariant, in every directory of a tree:
AGENTS.md is the real file; CLAUDE.md is a symlink pointing at it.
Imports the standard library and nothing else — no issue, no tracker, no
configuration, no login. That is not a stylistic preference: this walks whatever
directory it is pointed at, on any machine, and a package that reached for a
project's configuration could not be run outside a project. Two tests hold it,
see internal/AGENTS.md.
| file | what is in it |
|---|---|
mirror.go |
Sync, Check, Result, and fixDir — the seven branches |
mirror_test.go |
one case per branch, plus the walk, the skip list and idempotence |
layering_test.go |
the two tests that keep this package at the bottom |
Why the invariant
Two agent harnesses read two different filenames for the same document. A repository that keeps both as real files keeps two documents, and they drift — silently, until somebody reads the stale one and believes it. One real file with a link beside it is the only arrangement where that cannot happen.
AGENTS.md is the real file rather than CLAUDE.md because the convention is not
one vendor's: a repository that names its documents after a single tool has picked
a side it did not need to pick.
The seven branches
Every one of them is either lossless or a refusal. Nothing here deletes content.
| starting state | what happens |
|---|---|
AGENTS.md real, no CLAUDE.md |
create the symlink |
CLAUDE.md real, no AGENTS.md |
rename to AGENTS.md, link back |
CLAUDE.md symlink → AGENTS.md |
canonical; nothing to do |
CLAUDE.md symlink elsewhere |
re-point it |
AGENTS.md symlink → real CLAUDE.md |
reversed layout; swap it round |
| both real, identical content | replace CLAUDE.md with the symlink |
| both real, different content | refuse, and name the directory |
The last row is the reason the other six can be automatic. One of those two files is somebody's writing and no rule here knows which, so a merge is not attempted and not offered — the conflict is reported and the directory is left exactly as it was.
Two smaller refusals sit beside it, both about a symlink with no target: a broken
AGENTS.md with no CLAUDE.md beside it, and a CLAUDE.md pointing at something
that is gone. Neither is repairable without inventing content.
The link target is relative. CLAUDE.md -> AGENTS.md, never an absolute path:
a tree that is moved, copied, cloned or mounted somewhere else keeps working, and
an absolute link would point at wherever the repair happened to run.
Two properties the tests hold
A repair that fails halfway reports nothing. An unwritable directory, a race with an editor — the fix is abandoned and no line is added. Claiming a repair that did not happen is worse than silence: the next run finds the same state, and the operator has now been told twice that it was handled.
Sync converges in one pass. Every case in the table runs Sync twice and fails
if the second run still has work. This matters more here than it looks: the command
that wraps this package runs on PreToolUse(Bash), so a state that reported itself
fixed without converging would re-report on every Bash call, forever.
Check is the same walk with the writes turned off — one code path, not a second
implementation that might disagree — so a check that says nothing is a promise
about the run that follows it.
What is skipped
node_modules, __pycache__, venv, vendor, and every dot-directory.
Somebody else's tree is somebody else's business: a vendored dependency's
AGENTS.md rewritten here is a diff nobody asked for. .git gets the same
treatment for a second reason — it is not a place to be creating symlinks.
What does not belong here
The JSON a PreToolUse hook reads and writes, the decision to run at all, and the
exit status. Those are cmd's, in mirror.go there; this
package takes a directory and returns a Result. That split is what lets the
repair be tested against a temp directory without a hook payload anywhere near it.
Keeping this file true
- Scope:
mirror.goand its tests — the invariant, the seven branches, the skip list, and the two properties above. - Update it when a branch is added or its outcome changes (the table is the contract), a directory is added to or dropped from the skip list, or the link stops being relative.
- Do not document the command, the hook payload or the exit codes here.
internal/cmdowns those.