Bilan

Bilan

The completion number is this script's number, never yours.

It used to be narrated: it came from the session's account of itself, so a session that believed it was done reported 8 or 10 while it still held open carnet issues, had commits sitting unpushed, or had background work still running. Every one of those facts is machine-checkable, and bilan.sh checks them.

.agents/skills/bilan/bilan.sh            # full: local facts, one fetch, one CI query
.agents/skills/bilan/bilan.sh --cheap    # local only, no network
.agents/skills/bilan/bilan.sh sweep      # what a session that DIED left behind
.agents/skills/bilan/bilan.sh scope      # the files the limitation register scans, as bilan resolves them

Exit code: 0 = 10/10 · 1 = incomplete · 2 = the script itself failed.

--cheap is the status-line run, and it gives the full run's number wherever local evidence can settle the fact. Where only the network can, the cheap run states what it cannot know instead of guessing: commits that look unpushed against a fetch more than five minutes old (it caps at 9, "may already be on the remote", where the full run fetches first), a filed issue someone else may have closed, or a limitation label applied outside carnet.sh (cheap keeps the cap on both), and whether the issue a new marker names is live (cheap does not judge it). CI is printed, never scored, so skipping it changes what is shown, not the score.

Every scoring run also writes score<TAB>epoch<TAB>top cap to ${CLAUDE_CONFIG_DIR:-~/.claude}/bilan/<session-id>.score, so a status-line command can show the number without running anything: it only has to refresh the file with bilan.sh --cheap --json when it ages.

The rules

1. Run it before you give a number. Report the score it prints. If you believe a cap is wrong, say so in words and still report the script's number — arguing with the measurement is a conversation, overriding it silently is the failure this exists to stop.
2. A cap is a fact, not an opinion. Each one prints its own evidence and its own remedy. The score is min() over the caps, so one open carnet issue holds the whole session at 6 no matter how much else landed.
3. Failures never deduct. A red that is now green, a mistake found and fixed, a rough path — none of it lowers the number. The score measures completion, and only completion.
4. Friction is printed, never scored. Tool errors, interrupts and denials are counted from the transcript and shown for context. They do not cap anything.

What caps the score

This repo's shape

Worktrees and branches without an upstream. Work here commonly happens in .claude/worktrees/*, on branches that have no upstream at all: a branch is typically landed on main with git push origin <branch>:main rather than published. So a branch without an upstream is measured against origin/main — its commits that are not there are unpushed work, and the remedy says how this repo lands it. Measured against an upstream it does not have, a worktree's work would never be reported at all.

The validation marker is scripts/pre-push-validate.sh's: one line, <epoch> <sha>, in the checkout's own git dir. In a worktree that is .git/worktrees/<name>/validation-passed, so a marker stamped from the main checkout never validates a worktree's HEAD — the pre-push hook would refuse that push, and bilan says so first. The TTL is read from .githooks/pre-push rather than restated, so the two cannot disagree about when a marker has expired.

The stash is one stack. Every worktree pushes onto the same refs/stash, so a stash made on another branch was made in another checkout: it is stated and never counted. For this session's own stash the remedy is to apply or drop it by its exact ref — a bare git stash pop in a shared stack can take a peer's work.

The ledger directory is machine-wide. ${CLAUDE_CONFIG_DIR:-~/.claude}/carnet-claims/ holds the ledgers of every repo whose sessions use carnet, and each line names the register its issue lives in. An issue is a (number, tracker) pair: a question about it goes to its own tracker, and an issue on another repo's register is named as owner/repo#n, never as this repo's carnet#n. Every question goes over REST (gh api), never gh issue: that is GraphQL, which a cloud session's proxy refuses, and a refusal read as an answer kept a closed issue's cap. A tracker that does not answer at all keeps the cap and says so, rather than reporting the issue as open.

Uncommitted files that are not this session's

Several sessions can share one checkout. A peer's mid-edit file used to hold every other session at 7 — and those sessions were right to refuse to touch it, so they could not reach 10 no matter what they did. That was a category error: the score measures this session's completion, and a peer's in-flight file is not this session's incompleteness.

Two mechanisms fix it, and the first needs nothing from you.

The baseline. The SessionStart hook records which files were already dirty or untracked — every untracked file by name — and which commits were already unpushed, when the session opened. A path dirty before the session existed is definitionally not its work — that much is machine-decidable. Those are stated as a note and never scored. The hook records it once per session: SessionStart fires again on resume and after a compaction, and re-recording there would declare the session's own uncommitted work inherited. Its paths and its HEAD describe the checkout the session opened in and no other. In a worktree the session reaches afterwards no path is inherited — a path dirty in the main checkout says nothing about the same-named file there, and a peer's pre-existing worktree is what ack is for — and whether the session committed anything there is read from that checkout's own HEAD reflog: where its HEAD stood when the session opened, or the commit it was made at. The unpushed commits it recorded are inherited everywhere: a sha names the same commit in every checkout, so a peer's commit already unpushed when the session opened is not the session's to land from a worktree made on top of it either.

ack, for what goes dirty afterwards. A peer editing during your session is not covered by the baseline, so you say so once:

bilan.sh ack --why "a peer's version bump, written into this shared checkout at 10:16"

That clears the cap rather than softening it — the tracked-files cap and the untracked-files cap alike — and carries the reason into every later report. It is keyed to the exact set of paths each cap names — what the baseline already calls inherited is not in it — so dirtying one more file brings that cap straight back, and ownership is a property of the files rather than their contents, so a peer changing those same files again stays covered. Neither cap's remedy ever says to delete a file: the ones it names might be a peer's.

Why not attribute automatically? It was tried and it does not work. Claude Code records the paths a session touched under file-history-snapshot.trackedFileBackups, but only for the Edit/Write tools, so a session that writes its files through Bash leaves that map empty. Attributing on it would call a session's own work a peer's and stop blocking — the worst direction to be wrong in.

The dev-stack cap follows the same rule where a checkout has one: a stack already running under the same pid when the session opened is a peer's, stated and never scored, because the only way to clear such a cap would be to take the peer's servers down.

The three call sites

/bilan — on demand, the full measurement including CI.

The startup sweep (hooks/session-start-sweep.sh) — records the baseline, then looks for what a dead session left behind. A kill -9, a closed terminal or an exhausted context fires no exit hook, so the dead session can never report on itself; the session that opens after it looks instead, across every worktree of this repo and every ledger on the machine. It reports only this repo's register, and drops a dead session's claim once the tracker says the issue is closed, so a long-resolved issue does not keep reappearing as abandoned.

A ledger belongs to its session, so the sweep rewrites or deletes one only when that session has certainly ended. A session is judged by its id, not by the pid its ledger recorded — carnet writes that pid once, and claude --resume keeps the id under a new one — from the session files Claude Code keeps under its config dir ($CLAUDE_CONFIG_DIR and every ~/.claude*): a file naming the id with a live pid is a running session, and the sweep leaves it alone. When the sweep cannot tell — a session file still names the session under a pid that does not run here (a leftover of a crash, or a session in another pid namespace sharing the config dir, such as a container), the ledger's recorded pid still runs with no session file to say whose it is, or the ledger names no pid — it reports the claims as possibly still held, and clears nothing. The host name carnet stamps into the ledger decides nothing: the ledger sits in this machine's config dir, and a machine's name changes under it — a Mac renames itself when its name is taken on the network — so a session this machine ran under an earlier name is still judged, and cleared, as this machine's.

The ledger directory is shared, and not every sweep that reads it keeps to its own register. This one asks each claim's own tracker and leaves another register's lines alone. The sweeps of dravr-platform and mirroir-mcp, as they stand, do not: each asks its own tracker about every claim number in a ledger whose session it takes for ended, whatever register the line names. A claim held here can then be reported there as that repo's own carnet#n, or be deleted — and the ledger with it, once nothing is left — because that repo's issue of the same number is closed; if that sweep runs first, this one then finds nothing to report. The claim marker on the tracker is untouched: carnet.sh status <n> still shows who holds the issue and whether that session has ended.

The Stop gate (hooks/stop-gate.sh) — disarmed, and deliberately not wired. It would refuse a stop while the score was 8 or below. That is only as good as the number: a gate grading something the session did not do — a shared checkout's HEAD, a peer's red CI — blocks every session in that checkout over a commit none of them made, and each block spends a session's last turn arguing with a number about somebody else's work. A wrong number costs a paragraph; a wrong number that can stop the session costs every turn it had left, and fixing one misattribution does not remove the class. The script is kept, and its tests run, so re-arming it would be a decision about a script that works.