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>
114 lines
5.8 KiB
Markdown
114 lines
5.8 KiB
Markdown
# AGENTS.md — internal/project (ROOT)
|
|
|
|
**One question: which directory is the project.** Everything that is a fact about
|
|
a project — the issue store, the request-payload scratchpad, the tracker config —
|
|
is resolved from the answer, and the answer is found by one walk written once.
|
|
|
|
This package **depends on nothing** but the standard library, and it is the only
|
|
one in the tree with no other package below it.
|
|
|
|
| file | what is in it |
|
|
|---|---|
|
|
| `project.go` | `Marker`, `Anchors`, `Parents`, `GitDirOf`, `MainWorktree`, `Root`, and the paths resolved from it — `StoreRoot`, `PayloadRoot`, `ConfigPath`, `ScaffoldPath` — plus `NotFoundError` |
|
|
| `init.go` | `Init`: creates the marker, migrates an older layout in, gitignores `.kettle/`. `ClashError` is its refusal |
|
|
| `project_test.go` | the walk, including the worktree hop and the "no marker anywhere" answer |
|
|
|
|
## The walk
|
|
|
|
Anchors, first hit wins: `$CLAUDE_PROJECT_DIR`, then the working directory. Each
|
|
is searched up its parent chain for a `.kettle/` marker, and then — **only if that
|
|
found nothing** — up the parent chain of the **main working tree of any linked
|
|
worktree** met on the way, reached by reading `gitdir:` out of a `.git` *file* and
|
|
following `commondir`.
|
|
|
|
A marker, not a fixed number of `..` hops: how deep a caller sits below the root
|
|
is an implementation detail of the layout, and the layout is not a promise. Walking
|
|
up means every command sees one store from anywhere inside the project — including
|
|
from inside the store itself — while a `cd` into a *different* project correctly
|
|
answers with that project's store.
|
|
|
|
The worktree hop is one level of indirection, never two: a main checkout is not
|
|
itself a linked worktree, so it cannot chain and cannot cycle. Only a `.git` *file*
|
|
is a pointer; in an ordinary clone `.git` is a directory and there is nothing to
|
|
follow. A submodule's `.git` is a pointer too, but it points into
|
|
`<super>/.git/modules/…`, and `MainWorktree` refuses it on the `.git` basename
|
|
check — the tree it belongs to is already on the parent chain.
|
|
|
|
## Two rules that are not negotiable
|
|
|
|
**Nothing here resolves from the executable's own location.** Where an installation
|
|
keeps its files is a fact about the installation; whose issues a tree has is a fact
|
|
about the tree, and a binary installed in one place and pointed at another must
|
|
answer from the one it was pointed at. This is the whole reason the package exists
|
|
— the Python version resolved its store from `__file__` and wrote issues into a
|
|
versioned plugin cache.
|
|
|
|
**The marker is created by `kettle init`, never inferred.** `.git` was tried and is
|
|
in every clone, including this repository's own, which is how a plugin came to
|
|
resolve its store inside itself. No marker anywhere is an *answer*, not a fallback:
|
|
`NotFoundError` names the anchors the search began from — not the whole chain,
|
|
because an operator who sees the two places it started knows immediately whether it
|
|
started where they meant it to.
|
|
|
|
## Init, and the migration
|
|
|
|
`Init` is idempotent and every step announces itself, so `--dry-run` is the same
|
|
code path with the writes turned off:
|
|
|
|
- creates `.kettle/issues/` and `.kettle/payload/`;
|
|
- migrates an older store in, oldest layout first — `tmp/issues`, then
|
|
`.tea/issues`, and the same pair for `payload` — so a tree that skipped a
|
|
generation still lands in one place;
|
|
- adds `.kettle/` to `.gitignore`, unless some line already ignores it.
|
|
|
|
**Each migration is a move, never a copy.** Two stores is the state the marker
|
|
exists to prevent, and a store left behind at an old path is a store somebody will
|
|
edit by accident months later. When both sides hold a file of the same name it
|
|
stops with a `ClashError` naming up to five of them and changes nothing: two
|
|
versions of one issue, and which survives is not a decision a migration makes
|
|
quietly. The old `.tea` marker is removed only when the migration emptied it —
|
|
anything else parked in there is somebody's.
|
|
|
|
`.kettle/` is gitignored because an `origin: local` issue is the only copy of that
|
|
work and what goes into a shared history is the operator's call. Committing the
|
|
store is a legitimate choice; drop the line if the team makes it.
|
|
|
|
## Usage
|
|
|
|
```go
|
|
root := project.Root("") // "" when there is no project
|
|
store := project.StoreRoot("") // <root>/.kettle/issues
|
|
if store == "" {
|
|
return project.NotFoundError("") // names the directories it searched
|
|
}
|
|
```
|
|
|
|
A non-empty `start` overrides both anchors and exists so resolution can be
|
|
exercised against a scratch tree — which is what the test suite does, and why
|
|
every fixture also strips `CLAUDE_PROJECT_DIR`.
|
|
|
|
`MainWorktree` has a second caller now, and it is the one that made the function
|
|
worth having in public: `kettle init` refuses to run where it answers, and names
|
|
the main checkout instead. That rule used to be a paragraph in a skill somebody
|
|
had to read, which stopped being good enough the moment an interactive wizard
|
|
became the front door — a front door cannot assume anybody read anything.
|
|
|
|
## What does not belong here
|
|
|
|
Anything that reads or writes an issue, a config file or a socket. This package
|
|
hands out **paths** and one answer about directories; the store is
|
|
[`issue`](../issue/AGENTS.md)'s, the config is
|
|
[`config`](../config/AGENTS.md)'s, and the scratchpad is filled by
|
|
[`gitea`](../gitea/AGENTS.md).
|
|
|
|
## Keeping this file true
|
|
|
|
- **Scope:** `project.go`, `init.go`, `project_test.go` — the walk, the marker, the
|
|
paths derived from it, and the migration.
|
|
- **Update it when** an anchor is added or reordered, the marker name changes, a
|
|
new path is resolved under the marker (the file table and the walk section both
|
|
name them), a legacy layout is added to or dropped from the migration list, or
|
|
the worktree rule changes.
|
|
- **Do not** document what any resolved path is *used for*; that belongs to the
|
|
package that uses it.
|