Carnet

Carnet

The register is Atmosphere/atmosphere-carnet, named by registre.toml. It is private because this repo is public and an entry states precisely where a defence or a capability is incomplete. Many Claude Code sessions work it at once, and nothing on a GitHub issue says a session is on it, so peers collide: two sessions pick up the same issue and build the same fix twice, or find the same gap and write it up twice. A claim fixes that. It is three native GitHub facts that move together:

One script does everything: .agents/skills/carnet/carnet.sh (also reachable through the .claude/skills/carnet link). Never run gh issue against the tracker by hand — the script is the one path that keeps the three carriers consistent and the title shape uniform.

The rules

1. Claim before the first edit — and it happens without you. The PreToolUse hook claims every issue the prompt named as soon as you touch a write tool, so an issue you were told about is held before your first edit lands, and the hook tells you so. Run claim <n> yourself when the number never appeared in a prompt (you found the issue by searching, or you are picking up work mid-session), and when the hook tells you it could NOT claim an issue — gh logged out, the tracker unreachable: it is not held, and peers see it unclaimed. Not after the commit: a claim made after the work is done protects nobody.
2. A refusal is a peer, not an obstacle. Exit code 2 means another live session holds the issue, or a session on another host does. Tell the user who and which session, and stop. The auto-claim hook enforces this once: it blocks your first edit and names the holder. It does not block again — after that you are accountable, not the hook. Do not --steal on your own judgement — stealing is the user's call, and the stolen-from session is warned on the issue. A claim whose session has ended is not a refusal: release and close exit 1 on it and say so, and a plain claim takes it over.
3. Release when you stop, close when it is fixed. release <n> when you abandon or hand off; close <n> --why "…" --commit <sha> when the work landed. Both drop the label and the assignee and post a marker. If another session took the issue over, release posts nothing and only drops it from this session's ledger. A session that ends still holding claims is released by the SessionEnd hook, so a forgotten release is not fatal — but do not rely on it.
4. Unreadable is not unclaimed. When the issue's comments cannot be read in full, claim, release, close and status exit 1 and change nothing: the newest marker is the only record of who holds the issue, and deciding without it is how two sessions end up on one.
5. Every close says why. --why is mandatory and is what the next reader sees first. Add --commit <sha> whenever a commit resolved it: the tracker is a different repository, so carnet#N in a commit message is plain text to GitHub and never closes anything there. --commit posts the commit's URL on origin.
6. File through create. It reads the tracker from registre.toml, refuses a tracker that is not private (or whose visibility it cannot read), prefixes the title with the project — [atmosphere] — unless the title already starts with [, and always adds the atmosphere label. Titles are [<project>] <Thing> — one shape, no variants, capitalised first word unless it is an identifier. The body says where it is (file + symbol), what is incomplete, and what the fix looks like. The limitation label goes only on an issue that a LIMITATION(registre#n) marker in source will point at; plain findings get the project label alone.

Commands

C=.agents/skills/carnet/carnet.sh

$C claim 12                       # hold it: assign me, label, marker comment, local ledger
$C claim 12 --steal               # take it from a live or remote session — the user's decision only
$C release 12 --reason "handed to the transport session"
$C status 12                      # who holds it, is that session alive, which branch
$C status                         # every in-progress issue in the tracker
$C mine                           # what this session holds (no API call, works with gh logged out); --verify to check the tracker
$C create --title "<Thing that is incomplete>" --label bug --body-file /tmp/body.md --claim
$C close 12 --why "<what resolved it>" --commit <sha>
$C label 12 +critical -bug
$C tracker                        # the register this checkout files into (no API call)

Add --dry-run to any of them to see the gh calls without making them.

Read the thread before you implement — comments carry requirements the body does not: gh api "repos/$($C tracker)/issues/12/comments" --paginate -q '.[].body'. The script reaches the tracker through gh api (REST) only, because gh issue is GraphQL and a cloud session's agent proxy refuses every GraphQL query outside a pinned set of PR-review operations.

What the hooks do for you

• UserPromptSubmit (hooks/prompt-status.sh): when a prompt names carnet#N, registre#N, or this register's own name or issue URL (atmosphere-carnet#N, Atmosphere/atmosphere-carnet#N, …/Atmosphere/atmosphere-carnet/issues/N), one status line per issue lands in your context before you answer — carnet#12 · held by @alice · session Wiring (a3f9c2d1) on build-host [running] · feature/wiring · since …. Read it. If it says unclaimed, claim before editing. If it says [session ended — stale], a plain claim takes it over. Another register's issue — dravr-carnet#31, llm-registre#5, its URL — is not this register's and arms nothing: the numbers overlap. A peer message or a background task result gets the status line plus a note saying it armed nothing — see A peer naming an issue is not assigning it below. Lines are cached for a minute under the tracker's name, so a checkout that files into another register never reads this one's, and a cached line naming your own session is never served to you.
• PreToolUse (hooks/auto-claim.sh): claims those issues for you, on the first write-shaped tool call after the prompt that named them, and tells you what it claimed. Reading is not working — a question about an issue never reaches a write tool and never claims. A Bash call counts as an edit only when the command looks like one (a redirect into a file, sed -i, mv, git commit, …), because a session that edits through bash would otherwise never claim; what sits inside quotes is data, so jq 'select(.n > 5)' or grep -n '<version>' is still a read. If a live peer holds the issue it blocks that one tool call and names them — and names anything it claimed for you in the same step. A claim that fails blocks nothing: you are told carnet: could NOT claim …, and the hook tries again on your next edits (three attempts within the hour). Whether you hold an issue already is the newest claim marker's to say, never the ledger's: a claim cut off half-way — by the hook's timeout, or a failed marker POST — is in the ledger and still not held, and the next attempt finishes it. Subagents share the session's id, so one hook run at a time works the list; a write made meanwhile goes through and leaves it to that run. Before claiming it asks the transcript who wrote the prompt that named the issue: a /loop or ScheduleWakeup re-fire is text the model wrote for itself, and a peer message or task result is text no human wrote, so a list armed by any of those claims nothing and tells you carnet: NOT claimed — carnet#N came from a scheduled wakeup … instead. Take it deliberately if it is yours: carnet.sh claim <n>.
• SessionEnd (hooks/session-end-release.sh): releases everything this session still holds, from its ledger under $CLAUDE_CONFIG_DIR/carnet-claims/ — each claim in the register its ledger line names — and drops its pending list. Zero calls when nothing is held.

All three are wired in .claude/settings.json; the exact entry is at the top of each hook file, and test.sh fails when one is missing or when the PreToolUse wiring would swallow the hook's exit code. They act on the checkout the session started in ($CLAUDE_PROJECT_DIR), not on wherever it has cd'd since. What the PreToolUse hook tells you arrives as hook context (additionalContext): Claude Code does not show the model a PreToolUse hook's plain output. The auto-claim hook costs one stat when nothing is pending, which is almost always — it runs before every edit in every session, and a list nobody consumed is removed at session end, or by any session once it is an hour old.

What it deliberately does not do. It never claims from a prompt alone, so asking about an issue is free. It never steals. It forgets a pending list an hour old, so an issue mentioned long ago is not claimed by an unrelated edit. It never claims from a peer message, a background task result, a wakeup prompt the session scheduled for itself, or terminal output pasted into the prompt. And it never blocks twice for the same issue: a permanent block would deadlock a session over an issue that was only mentioned in passing.

A wakeup you write is not an assignment you received. When you schedule a wakeup (/loop, ScheduleWakeup), the prompt that comes back is yours, and the hooks know it: the prompt hook cannot tell at submit time (as of Claude Code 2.1.276 the payload carries no source yet, and the transcript entry is written after the hook runs), so it records the prompt id, and the claim hook reads that entry — promptSource: "system", isMeta: true, scheduledTaskId — before claiming. Without that, a session that wrote "comment on carnet#N" into its own wakeup would hold #N for as long as it ran, the user never having typed the number. Do not put issue numbers into a wakeup prompt as a to-do list for yourself; and if you are told a claim was refused because the prompt was a wakeup, that is the hook working.