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>
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# 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`](../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`](../cmd/AGENTS.md)'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.go` and 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/cmd`](../cmd/AGENTS.md) owns those.
|