shoalmark

Get a better-performing human Owner.

Agents do not wait for tools. They wait for their human. Asked what slows them most, three agents, run separately, gave the same answer, by a wide margin: the Owner's unanswered questions — one question, open three days, held three packages. And where the human does keep up, they keep up by not reading: in the repository this tool came from, 200 pull requests were merged in 22 days, 85 % of them less than a minute after opening, none with a review. Blocking and stamping have one root — a person asked for many small decisions in the middle of the work.

So the human is asked once, earlier, and in writing: what the work is for, what it must never do, what done has to prove. They see what waits for them, how long, and what it blocks — first, above everything else. The agents get what they need to run start to finish: state that outlives a session, one source of truth, a gate that refuses a done without a commit behind it. Less work and distraction for the human; more throughput and less friction for the agents.

What exists today: the tracker, the gate (it refuses a done without a commit behind it), the board with waiting for you on top, next: owner, a cold-start answer in one command (--next) — with git, on Windows, macOS and Linux, in any language. What is the direction, not yet built: the signed mandate, questions that carry a default and a deadline, the rest of evidence-checked done, the digest — explored, with what would kill each claim, in shoalmark's own tracker (FM-005, work-tracker/evidence/FM-005/design.md). Trust is earned there from the Owner's own answers before anything runs unattended.

In this beta:

• Not a migration tool: it imports no ticket system and starts from your repository's own work. A path for a fleet that already runs a system of its own is filed, not built.
• For one person in charge and their agent fleet. Several people in charge are not tested in this beta; support for them may come later.
• Not proof that work is right. In Git or Subversion changes being checked, a move to Shipped must name in its ship log a commit already in that change's history that changes something outside the records (on Subversion, a revision). This evidence rule does not cover Closed. Validation reports a violation and exits non-zero. An installed Git commit hook can refuse the commit on that failure, but is optional and can be skipped. To enforce the check before merge, require a passing --check on the branch through your project's CI and merge rules; shoalmark does not set those up for you. Whether that commit did the job is what a review is for.
• Made and tested on git with GitHub. Subversion passes the test suite but has not been used in real work: try it, without a guarantee. On Subversion it runs without git installed, from the release archive, and each run says what it cannot verify there: commit signatures and server-authenticated authors. Signed answers need a git repository, and the pull-request queue a git repository on GitHub and GitHub's command line, gh.

Git worktree identity and commit-trailer reports (--whoami, --session-trailer, --sessions), the forge queue (--queue) and signed answer-branch acts (--answer, --done, --due, --revoke) require Git. Under Subversion, --session new generates an id without checking a Git commit registry. A server login can attribute an SVN revision; it provides no cryptographic commit signature, and a local working-copy label proves no author. Checks that need server history refuse when that history cannot be read.

For archive acquisition, unpack the release ZIP and keep its complete inventory, including RELEASE and the probe files. Run the unpacked tool with --root <project directory> --vendor <destination>; --vendor names the destination and takes its source from the running tool's folder. It validates every exact source byte and required file before copying the 19 tool files. The manifest verifies the archive's internal bytes and completeness; obtain the release from the source you trust. The manifest and probe files remain acquisition inputs. A tag-none dry-run archive needs the existing --allow-untagged; neither that flag nor --partial permits an invalid or incomplete archive. Full SVN gate, board, history, protection and installed-entry qualification remains separate from archive acquisition; no complete operation without Git or new proof-platform result is promised here.

A convention, Stage 0: a requirements/ folder holds one line per requirement — id, shall, source, acceptance criterion — one text for developer and tester; a tracker cites the id. shoalmark has the convention only: checks and traceability are later.

A shoal mark is a mark set to show shallow water — a stake or a buoy. It tells a shoal where not to run aground.

A work tracker that lives in the repository it tracks: one Markdown file per work item, one Python file that reads them all, and checks you can run locally and in your project's CI. It needs no server, database or account of its own, and no dependency beyond Python 3.9. This page is written for the agent that has to use it. Find your situation, do what it says.

<cmd> below is python3 tools/shoalmark/shoalmark.py in a repository that vendors it — or whatever command that repository's own messages name. Every command finds the repository by itself: the nearest shoalmark.toml, else the nearest Git or SVN working-copy root. --root DIR selects the consumer project when the tool lives in a different folder; the tool's own source does not supply that project's identity or authority. Printed retry commands for answers and acts use PowerShell argument spelling on Windows and POSIX shell spelling on macOS and Linux.

The five rules

1. The tracker is canonical. Spec, state and record of a piece of work live in its tracker — never in a side plan, a chat or a TODO comment. What is true now is rewritten in place; only the ship log is append-only.
2. Look before you file. The default is a slice of a tracker that exists, not a new one.
3. An id never changes and says nothing that can. MSR-012 — the kind of work is a tag, a story is a field.
4. The seat judges, the command applies. Never hand-edit triaged: tier: rank: or a park.
5. Close out by asking what this made obsolete — and delete it in the same change.

1. Start — what do I work on?

bash <cmd> --next

Prints the Owner's current path, then the ranked work in order — each with its next move, what it still needs, and the opening of its What is true now — and ends with START WITH: <id>: the first ranked tracker whose move is yours (review · run · script · build), not the Owner's (owner) and not a wait. Read that tracker. Work on a branch that carries the id: feat/msr-012-slug, fix/msr-013-slug.

Nothing ranked? It says how many trackers wait for a triage pass. No path written? Only the Owner writes it (<tracker dir>/TRIAGE.md) — ask; do not invent one.

2. File — look first

bash <cmd> --new "what is wrong, in one sentence" <cmd> --new "what is wrong, in one sentence" --tags bug # the kind of work, written into `tags:` as it is filed

It prints the closest existing trackers before it writes the file. Open the top hits. If one of them already owns this, add a slice to it and delete the new file. Otherwise fill the front matter:

```yaml

id: MSR-014 # written for you; equals the filename and the first heading status: Proposed # Proposed · In Progress · Parked · Reserved · Shipped · Closed considered: MSR-003, MSR-009 # what you held this against — or: none. REQUIRED: the gate refuses the file without it tags: bug # at most 3, from [tags] in shoalmark.toml — a closed vocabulary epic: MSR-003 # optional: the story this is a chapter of hook: "The problem as filed, in two or three sentences — this is the INDEX row."

```

Then the body: # MSR-014 — title · ## What is true now · ## Why · ## Done when · ## Ship log. <cmd> --schema prints every key, its shape and who may write it.

Tags. --new "…" --tags bug writes tags: into the new tracker. --tags takes a comma-separated list from [tags], at most three, case aside; a tag outside the vocabulary is refused before anything is written, and --tags without --new is refused. There is no filing freeze: R15, the Owner's ruling of 12 October, removed it, and every filing is written. A shoalmark.toml that still sets freeze_at or freeze_tag is named in one line by --new and --check, never refused; delete the line.

3. Stop — leave the fix

The next session starts cold. Before you stop:

• Rewrite What is true now so its opening says what is left — one remainder, stated plainly.
• Set next: to the next move: review (built, a branch waits to merge) · run (built, a real run is owed) · wait (a date or an event) · owner (the Owner's act alone) · script (mechanical) · build (anything else).
• On a build, with the tracker open, set kind-of-problem: — obvious (a script could do it) · complicated (found by reading) · complex (found only by running) · chaos (harm now).
• Waiting on something? blocked-by: MSR-009, Owner — the ruling awaited. Blocked is derived and clears itself.
• Done? status: Shipped (merged — not deployed), with the commit that built it named in a ship-log row — the gate refuses the move without one (§5) — and remove rank:. Nothing was built? status: Closed. A story stays open while a chapter is.

4. Triage — you judge, the command applies

bash <cmd> --triage # writes <tracker dir>/evidence/triage/triage-<today>.md and prints the rules

Fill the Verdict and Reason cells, row by row, from the row. Run the same command again — every ten rows or so, and at the end: it applies what you filled, refreshes INDEX.md, keeps your rows, lists what is left.

A raise is one line under a tracker's ## Raised — - <date> · <who> · <fact> · <source> · undermines: <what>. Dated after the tracker's triaged: and naming a signed rule it undermines — path N of the current path, or <ID>'s answer of a tracker they answered — it puts an open tracker under triage and on the next worksheet, marked RAISED, with the raise in its Now cell: a raise naming a signed rule re-judges the tracker the same day; any other raise waits for the next pass (the Owner's answer, FM-033). A day decides: a raise written after the same day's pass is re-judged by that seat's own re-run. One tracker, two rows: the re-judgement is a second filled row below the first, and the LAST filled row in the file is applied; the earlier is left as it is — the record of the first judgement — and every run names it, superseded on this sheet by the later row (FM-036). Never strike it to make the other apply.

Never write a note into a tracker during a pass; the reason lives in the worksheet. Never touch the current path. The pass is the seat's judgement, dated by its commit; the Owner lands it by merging; a row they disagree with is re-made by the seat on their word, or ruled by their signed answer — a merge rules nothing: an answer is written and signed, and a merge is not one.

5. The gate refused me

<cmd> regenerates INDEX.md; <cmd> --check only looks. Exit codes: 0 green · 3 drift — a tracker changed and nothing regenerated: run <cmd> · 4 a violation — fix the tracker; regenerating will not clear it · any other code comes from the repository's deriver (§7) and its message says why.

Only the Owner changes their intent and their current path (FM-037, their word of 2026-09-25). --check walks the branch's own commits — HEAD less origin's default branch, merges included — and reads, for each, what a pass reads as theirs: the text under ## The intent and ## The current path of TRIAGE.md (the repository's [headings] names, or the English ones), from its heading line to the next ##, each commit under its own shoalmark.toml — its tracker_dir names the file. Byte for byte: whitespace counts, since the text is printed as written and a comparison with nothing normalised has nothing to slip past. A text that differs from the parent's is a change — a heading renamed or removed, TRIAGE.md deleted, moved away from its name or out from under the tracker directory, tracker_dir pointed at a directory whose TRIAGE.md reads otherwise or not at all; a merge's change is only a text no parent had (FM-019), what it carries having been judged on the commit that made it. A change is refused, exit 4, unless it is the Owner's signed commit: %G? G, the signer principal (%GS) the author's email, and the author the Owner — or a seat [rights] gives answer — in the default branch's configuration — never the branch's own, so a branch that names a seat the Owner, or drops signed from theirs, does not judge itself. Nor its keys (the Auditor seat's AU-19): a signature is verified against the default branch's copy of the signers file gpg.ssh.allowedSignersFile names, where that file sits in a checkout of this repository — never the branch's own — so a branch that appends its own key under their email vouches for nothing; the answer gate and --queue verify the same way. The signers file itself — that one, and <tracker dir>/allowed_signers — is kept like the two sections: a change to it is refused unless it is their signed commit. Its first version therefore lands on the default branch by their own hand: a branch cannot prove a key the default branch does not hold — until it is there, no SSH signature verifies against a signers file in a checkout (the cold re-review's R2), and a new key verifies once it is merged there: --answer asks the same test before it pushes (R1). ## Passes and the rest of the file stay open to seats; a scaffold where there was none is accepted — any whose words the readers know (--init's, the German one, 0.1.0's bare lines: AU-20). The reading of a move (the pass's R7): the guard judges what the tool reads, so a move of the whole tracker together with its key that leaves both sections byte-identical is no change — ae1f05e, the tracker's move out of docs/, is accepted on its text, not by its date; refusing every move and exempting that one by date was the alternative, not taken, because it keys a hole to a calendar and refuses a move that leaves every word of theirs as they wrote it. The commit-msg hook refuses a seat's such commit before it is made; it sees the author only — git signs after its hooks run — so the Owner's own passes it on their name and --check on the branch, the gate, judges the signature. --queue reads such a branch wait: TRIAGE.md changed unsigned. Where their owner is not signed, it proves the author only, and says so. Subversion is out of scope: its working copy carries no signature, so nothing there can tell their commit from a seat's. Its limit (FM-007): a commit signed with the Owner's key passes; at tier 0 any process on their account holds that key.

Never --no-verify. Never hand-edit INDEX.md — it is generated.

6. Install and upgrade

bash git clone --branch vX.Y.Z https://github.com/shoalmark/shoalmark /tmp/shoalmark # a release: a clean clone at its tag python3 /tmp/shoalmark/shoalmark.py --vendor <repo>/tools/shoalmark # a pinned, self-contained copy + PIN (sha256) cd <repo> python3 tools/shoalmark/shoalmark.py --init --key MSR # shoalmark.toml · TRIAGE.md · .gitignore · the contract in AGENTS.md · a CLAUDE.md router python3 tools/shoalmark/shoalmark.py --install-hook # plain git hooks, and the copy of the tool they all run; a hook that is not shoalmark's is never overwritten

--install-hook writes three hooks, the three that judge a commit — pre-commit, prepare-commit-msg and commit-msg — and every one runs a copy of the tool kept in the git directory (shoalmark-trusted/, shared by every worktree), never the tool a branch brings. No hook refreshes the board (R11, the Owner's ruling of 12 October): nothing shoalmark writes runs after a checkout, a merge, a rebase or a pull. The board is rebuilt by an explicit run — --html-only, or the plain run — by the commit's own hook where the commit stages a tracker, and by --answer, --done, --due and --revoke right after each pushes. Where an earlier version wrote post-checkout, post-merge or post-rewrite, the next --install-hook removes each one exactly as that version wrote it, with a line; a hook of those names that it did not write — or one changed since — is kept as it is, and named. A commit's hook writes only inside the repository, outside its git directory and through no symlink, and it fails closed: where the copy is not there, refuses, or does not finish within 35 seconds (SHOALMARK_BOARD_SECONDS gives it longer), the commit is refused with one line. No hook runs the repository's deriver: where there is one, the commit's hook leaves INDEX.md and the files it derives as staged and says so in one line — run the tool before committing; CI's --check, which runs the deriver, holds them. --install-hook refuses a hooks folder inside the working tree — a core.hooksPath there, or a symlink into it — where a branch could change the hooks themselves, and writes no hook and no copy. Only --install-hook writes the copy — from a pinned copy that passes its PIN, else from the working tree's tool, and it says which commit and branch — so run --install-hook on your default branch, and again after upgrading; where the tree's tool differs from the copy, a hook still judges with the copy and prints one line that says so. A person, an agent and CI run the repository's own tool, as ever. Developing the tool itself means installing the branch's copy deliberately: --install-hook on that branch, which warns that the copy carries that branch's tool. On git and on Subversion alike, after a checkout, a pull or svn update, run --html-only to rebuild the board.

Then the Owner writes the intent and the current path in <tracker dir>/TRIAGE.md. Nobody else edits those two sections. The intent is three lines in their own words about the repository as a whole, never one feature of it: what this repository, all of it, is for · what is true when it works · what no pass or seat may do to get there. --init writes an example in italics, a whole product, for them to overwrite:

markdown - **for** — *e.g. a village library's lending, all of it: members, loans, returns and the shelf in one record the librarian trusts* - **so that** — *e.g. a member finds a book and a librarian finds a member in one look, and nothing on loan is lost* - **never** — *e.g. lend what the catalogue does not hold, or drop a member's record before their last loan is back*

A pass reads everything they write under the intent and leaves out only the scaffold's own lead-in and examples, recognised by their exact text, never by italics, bold or length: an example with one word changed is theirs.

--vendor vouches for what it copies. It refuses — exit 4, nothing written — a source that is not the whole tool (it names the missing files), a source that is no release (a git checkout whose HEAD is exactly at v<VERSION>, with a clean tree — it names the HEAD and the changed paths), and a copy in the target that was edited in place. A consumer runs a release, never a working copy. --partial copies an incomplete source anyway and --allow-untagged a working copy; each says so in the PIN. The PIN's first line is the manifest — # shoalmark X.Y.Z · tag vX.Y.Z · commit <sha> · vendored <date> · complete — and the consumer's --check checks it (that exact form, the tag against the version, the version against the copy's VERSION) before it prints where the copy came from, with a warning for an untagged or partial one; any other line is named, and the copy called unverified.

Upgrade: --vendor again from the new release's clone (it names the tag, prints what changed since the version it replaces, and refuses a copy that was edited in place), then --init again to refresh the contract between its markers — your text outside them is kept.

What lives where, by convention — no setting names any of it:

What invites and notifications left

R9 removed --invite <id>, --notify and --standup FILE.ics. What they wrote, or told you to add, is yours: the tool reads, runs and removes none of it. --standup and --owner name each piece they can see, after the digest, under LEFT BY INVITES AND NOTIFICATIONS, on every run until you remove it; the board names none of it.

• Calendar files. --invite <id> wrote <tracker dir>/evidence/<id>/<id>-act.ics; --standup FILE.ics wrote where you named it. Both runs name such a file wherever it is in the repository — its tree walked through no symlinked folder — known by its first three lines; one written outside the repository is not seen. Delete the files, and the events you imported from them — the stand-up's weekly event says to run --standup, which stays.
• The schedule. Before R9 this README gave --notify a cron line, which writes ~/.local/state/shoalmark/notify.log, and a launchd agent, ~/Library/LaunchAgents/app.shoalmark.notify.plist, which writes ~/Library/Logs/shoalmark-notify.log. Each run of either now prints only R9's line and exits 2. Take the cron line out with crontab -e, or launchctl unload the agent and delete its file; then delete the log. Both runs name the logs, with when each was last written, and the agent's file. The tool starts no program to read a crontab, so a schedule you named otherwise, or that logs elsewhere, is not seen.
• What --notify remembered. notified.json in $XDG_STATE_HOME/shoalmark/, else ~/.local/state/shoalmark/ (on Windows %LOCALAPPDATA%\shoalmark\). Delete it, then the folder once it is empty.

Seats

Who is at the keyboard, and what that seat may change. Four rights, each a front-matter transition the gate sees in a diff: answer (the three answer lines) · ask (next: owner, and clearing an answered ask with its record) · close (a terminal status) · triage (considered:, kind-of-problem:, tier, rank); anything else is open to every seat. The tool knows the Owner, and three seats with their rights built in — planner ask · close · triage, reviewer triage, builder none; principal and implementer, their former names, still read and hold the same — any other name says so in [rights], in the same diff as anything it would allow. The Owner is not a seat. A top-level owner = "[email protected] signed", before any table, names them — one identity or a list of them, signed per identity as for a seat — and they hold all four rights. A signed identity is an email address, and it verifies by SSH only: the commit's signature is SSH, good under the default branch's signers file, and its principal equals that email exactly — never a principal that merely contains it, never the commit's author standing in for it. A signed identity that is not an email is refused when the configuration is read, exit 1, with the way to migrate: write the email the signers file names for the key. A GPG or X.509 signature on a signed line is refused: sign with SSH; GPG returns with a fingerprint binding. [seats] owner is still read, as its old spelling: both present and the same are read once, both present and different are refused at configuration, in one line naming both, and so is an owner key inside any other table (in [rights], a list of rights is the Owner's own), which is where a line meant for the top lands when it is written below a [table] header. Absent [seats] and owner, nothing of this is enforced. The seats are called Planner and Builder in prose and in [seats]: this repository's keys are planner and builder, each with its GitHub App's bot address beside the old one (§Seat icons on the forge). A merge is judged by what it changes itself — the files where it differs from every parent — under the merger, and an answer or a next: owner it sets in its own change is refused: set it in a commit of its own. Every commit it brings is judged under that commit's own author and signature: an ordinary commit against its own parent, a merge, nested at any depth, by what it changes itself. A merge that equals a parent in every tracker adds nothing, and never launders a commit that was made without the hook.

toml owner = "[email protected] signed" # the Owner, not a seat: at the top, before any table; `signed` as for a seat [seats] # a name you choose -> the identity version control reports planner = "planner@seat signed" # `signed`: an email; the commit is SSH-signed under a key trusted for exactly it builder = "builder@seat" [rights] chef = ["answer", "close"] # only for a name of your own — not owner, planner, reviewer or builder

The badge: git config extensions.worktreeConfig true once, then git config --worktree user.email planner@seat in each seat's worktree. A signed seat's key belongs where only that seat runs — a container, later; the Owner's key is never in a seat's environment. This catches an agent that does not know the rule, not one that lies: that is FM-007's class, and nothing moves work except the Owner's signed answer. On Subversion the identity is the server account and signed is refused — the server authenticated the commit, and the gate reads the author it recorded (svn blame --xml, as the answer gate does). One seat = one SVN account whose credentials exist only in that seat's environment (a container, or its own Windows user), never the Owner's cached ones (~/.subversion/auth, the Windows credential store); the svn command line runs no hook, so a protected edit is committed there, and --check after the commit is what judges it, with the board's sent back group as the backstop. A seat's charter — how it thinks, a bold Planner against a steady one — is <tracker dir>/seats/<name>.md, read by the agent at start, never by the gate.

Seat icons on the forge

A commit whose author email is a GitHub App's bot address, <id>+<slug>[bot]@users.noreply.github.com, shows that App's icon on the forge — so each seat can wear its own. Per seat, one GitHub App owned by the organisation: no permissions, webhook inactive, no private key, no client secret; only the icon uploaded. The bot's id is id in GET /users/<slug>%5Bbot%5D; if that answers 404, install the App on the organisation — only the repository where the screen offers a choice, and anyway where it offers none: with no permissions and no key, nothing can act through it. Then [seats] lists the new address beside the old one — a seat's value is a string as ever, or a list, and every identity in it is that seat — so history and the branches in flight keep resolving:

toml planner = ["planner@seat", "12345+shoalmark-planner[bot]@users.noreply.github.com"] # each item may end in `signed`

Each seat's worktree then takes the new address: git config --worktree user.email '12345+shoalmark-planner[bot]@users.noreply.github.com'. Nothing else changes: the seat's rights, its Session: trailer, and the Owner's signature, which stays theirs. signed is read per identity; an identity under two seats is refused at configuration, in one line naming both. The seats are planner and builder from 0.19.0 — principal and implementer still read, and hold the same. This repository made the change in one step: the keys renamed, each seat's bot address beside its old one, and gtm, a seat of its own until then, an address of go-to-market; a session begun under a seat's old name (<id>/implementer-<n>) still reads as the seat's. A seat is it, not a person — its texts say it on purpose; they is for the Owner and any person.

Sessions

The seat says who may; it cannot say which run: two sessions of one seat are one author in git. So a seat's worktree carries a second setting beside its badge, and every commit made there names its session.

bash git config --worktree user.email planner@seat # the seat — read by the gate for rights git config --worktree seat.session a9f3c2d1 # the session — the harness's session id, its first eight hex characters; # a sub-agent derives its id from its parent's: a9f3c2d1/reviewer-1; # a session with no parent and a harness with no id: `<cmd> --session new` git config --worktree seat.harness aefd1a3520c000231 # the id the HARNESS gave this seat, written by whoever spawns it from the spawn's # result — Claude Code's session id, or a sub-agent's agent id; Codex's thread id

The trailers: --install-hook writes a prepare-commit-msg hook that appends Session: <seat.session> and Worktree: <the checkout's directory> to every commit made in that worktree — never typed, and a trailer the message carries already is left alone. A repository with no seat.session (the Owner's checkout) gets nothing appended: their signature is their id. Read them back with git log --format='%h %ae %(trailers:key=Session,valueonly)'.

The model and the effort are appended beside them — Model: and Effort: — from the harness's own log, never from what the seat says of itself. The log is found by the id in seat.harness and by nothing else: the one file whose name carries it, ~/.claude/projects/<slug>/<id>.jsonl for a session, ~/.claude/projects/<slug>/<session>/subagents/agent-<id>.jsonl for a sub-agent, ~/.codex/sessions/…/rollout-*-<id>.jsonl for Codex (CODEX_THREAD_ID is read where seat.harness is unset). Not the log's cwd — a transcript names the directory its session was launched in on every turn, sub-agents included, so a seat working in its own worktree would match none, and one working in the launch directory would match them all. From the file the tool reads only top-level fields of the newest turn that has them — Claude Code's message.model and perTurnEffort, Codex's turn_context model and effort — never a message, never a tool's result. Two files for one id: --whoami refuses (exit 2, both paths named) and the hook writes no Model: and no Effort: (and does not stop the commit). No file, or no seat.harness: no trailers, and the board shows —. A trailer the message carries already is left alone, each key on its own.

text $ python3 shoalmark.py --whoami From: a9f3c2d1/reviewer-1 reviewer (reviewer-2) · claude-opus-4-8 · high

A repository with its own hook runner adds three entries, each running the copy of the tool in the git directory as --install-hook's own hooks do — with lefthook, the session rule on every commit, the trailers, and the judgement of the commit with its message:

yaml pre-commit: commands: session: # the session rule on EVERY commit, a tracker staged or not run: python3 -I "$(git rev-parse --git-common-dir)/shoalmark-trusted/shoalmark.py" --root "$(git rev-parse --show-toplevel)" --session-check prepare-commit-msg: commands: session: run: python3 -I "$(git rev-parse --git-common-dir)/shoalmark-trusted/shoalmark.py" --root "$(git rev-parse --show-toplevel)" --session-trailer {1} commit-msg: commands: judged: # where `judged_before_build` is on: the commit judged with its subject (FM-033) run: python3 -I "$(git rev-parse --git-common-dir)/shoalmark-trusted/shoalmark.py" --root "$(git rev-parse --show-toplevel)" --commit-msg {1}

Run --install-hook once, on your default branch, so the copy is there: it writes the copy, leaves the runner's own hooks alone and names each with the line to add, exit 4. Where the copy is missing, each entry fails — Python cannot open the file, exit 2 — and the runner refuses the commit until --install-hook writes it again. A hook runner reads its configuration from the tree, so a merged branch's configuration runs whatever it names: these entries keep the tool out of a branch's reach, not the runner's configuration. shoalmark's own --install-hook is the safe default — its hooks are plain files in the hooks folder git reads, and they run only the copy.

The commit hook is best-effort. The gate is --check on the branch, and it must be green on the pull request's head before merge. A bypass of the hook alone, which --check catches, is P3. Git's --no-verify skips any hook by design; what protects the default branch is --check on the branch. Without origin/HEAD — a CI checkout often has none — --check asks origin for its default branch where origin/main or origin/master is all it holds, and refuses in one line where origin cannot be read — a private repository's checkout that keeps no credentials (persist-credentials: false), on a push to the default branch or with fetch-depth: 0, or a clone offline: run git remote set-head origin <default> first there.

The registry is a report: <cmd> --sessions prints it from the trailers of the checkout's history — one row per session id: its seat (the author through [seats]), its first and last commit, how many commits carry it, and its worktree. Nothing is opened, closed or kept in a file, so two branches that land never conflict on it: a session is what its commits say, and it ends at its last one. An id seen in two worktrees is named under the table.

text | Session | Seat | First commit | Last commit | Commits | Worktree | |---|---|---|---|---|---| | a9f3c2d1 | planner | 2026-09-24 07:28 · 049a9ab | 2026-09-24 11:02 · 5e1f0a2 | 9 | planner-a9 | | a9f3c2d1/reviewer-1 | reviewer | 2026-09-24 09:40 · 7c2d8e1 | 2026-09-24 09:52 · 3a7d1e0 | 2 | reviewer-2 |

Until 0.18.0 the registry was <tracker dir>/sessions.md, written by --session open and --session close and read by the gate. Both commands are gone — each says so and exits 2 — and --check warns in one line where the file is left: delete it; history keeps its rows.

The gate holds one rule. A commit by a seat [seats] names — never the Owner's, never an author outside [seats] — must carry a Session: of the shape <8 hex> or <8 hex>/<seat>-<n>, and where it names a seat, that is the author's seat — or a name the seat had: principal for planner, implementer for builder, the name of an old <name>@seat address it lists — and a label that is another seat's own name, or that two seats claim, passes for none. Exit 4, and one of three lines:

text refused: this commit by planner@seat carries no Session: trailer — set `git config --worktree seat.session <id>` in its worktree: … refused: this commit by planner@seat carries `Session: q7` — a session id is eight hex characters, or `<id>/<seat>-<n>` for a sub-agent refused: this commit by planner@seat is the seat planner, and its Session: a9f3c2d1/reviewer-1 names the seat reviewer

The pre-commit hook --install-hook writes runs it on every commit — --session-check, the session rule alone, a tracker staged or not. It judges what the rights are judged on: the commit being made (by its worktree's seat.session, the trailer its hook will write), the commit at HEAD by its trailer and, in --check on a clean tree, every commit since origin's default branch — the newest alone where none is found, and none where the tree has uncommitted edits, as --check says — and every commit a merge brings, each by its own. A repository adopts the rule with its first Session:: a commit whose history carries none is not judged, so a repository that never set seat.session is not refused when it vendors.

Verdicts: a review commit names the tip it judged — the Reviewer types this trailer: Reviewed: <sha>. --check reports each verdict of the last triage_days days. The reviewed range is the branch's own commits — git rev-list <tip> ^<trunk> --no-merges (the default branch as --check reads it, else main, else master), less other verdicts; for a tip the trunk has since merged, the trunk as it stood before that merge — so what the branch merged in from the trunk is not its, and the report does not change when it lands. The verdict is independent when its session's root (a9 of a9/reviewer-1) is none of the range's sessions' roots, same session when it is one of them — a Reviewer run as a sub-agent of the author's session is not independent — untraced when either side names no session, and on trunk — not a branch verdict when the tip is on the trunk's own first-parent line. A count, not a refusal: the refusal is a later slice, after a week of counts. --queue reads a verdict's word from its commit's subject — READY, READY WITH FINDINGS, READY TO TAG or NOT READY: a verdict commit says one of them.

Seen: the board's strip is one line per parent session with a commit in the last day, its sub-sessions folded into it — sessions · 2 in the last day (9 with their sub-sessions), then a9f3c2d1 planner (planner-a9) · builder 1–6 · reviewer 1–5, 7 (a run of three or more is a–b). A line opens on each member's worktree, model and effort (— where its commits carried none). A parent that made no commit of its own still has its line, its seat and worktree —, derived from its sub-sessions' ids. It is read from the trailers alone, never from a transcript. Under it, reviews this week · independent n · same session m. --owner, the digest, carries the same grouping — a header with the two counts, then one line per parent — and ends with the queue where gh reads the forge (what to merge, above). Labels: sessions.recent (now with {1}, the count with sub-sessions) and reviews.* (§9).

7. The one seam: a deriver

The core knows nothing about releases, deploys or product areas. A repository that needs them puts one executable at <tracker dir>/derive. The core runs it first, on every run — so keep it fast — with this on stdin:

json { "root": "/abs/path", "mode": "write", "flags": [], "trackers": [ { "id": "MSR-012", "status": "Shipped", "file": "MSR-012-x.md", "fm": { "version": "1.2.0" } } ] }

and reads this from stdout:

json { "MSR-012": { "Ver": "1.2.0", "Release": ["1.2.0", "1.2.0 ✓"], "_needs": [] }, "_keys": { "version": { "shape": "\\d+\\.\\d+\\.\\d+", "says": "the release it shipped in", "who": "the ship commit" } }, "_problems": [ "MSR-014: version on work that has not shipped" ], "_index": [ "Ver" ], "_board": [ "Release" ], "_notes": [ "**Ver** = the release it shipped in." ], "_files": { "docs/RELEASES.md": "…the whole file…" } }

• Each value key is a column in INDEX.md and on the board, and a view, a fact and a search word on the board. _index / _board narrow which goes where (default: all). A value may be [value, display]: the value groups, sorts and is printed in INDEX.md; the display form is for the board's cells.
• _keys join the schema gate — add a key, never redefine one. _problems fail the commit like the core's own. _needs (per tracker) are shown beside the core's own marks. _notes go into INDEX.md's header.
• _files are written, drift-checked (--check) and staged (--print-written) by the core. A deriver has no side effects, and nothing derived is ever stored — so nothing derived can be stale.
• A non-zero exit refuses the run before anything is written — a crash included, and silence past 60 s. Say why on stderr.
• mode is write · check · read. flags are what was typed as --derive-flag NAME on this run.
• A deriver is told things on stdin and never reads the environment — the core runs it with PATH, HOME, the locale and nothing else. A git hook inherits whatever the shell that ran git commit had exported; a deriver that listened to that would let a stray variable decide what gets staged.
• A wrapper script may set SHOALMARK_CMD so every message names the repository's own command.

8. Working on shoalmark

bash python3 test_shoalmark.py && python3 test_core.py # every check builds its own throwaway repository /usr/bin/python3 test_shoalmark.py # the oldest Python promised: 3.9, the one macOS ships

Where Chrome or Chromium is installed the board is rendered and read back. test_core.py pins the core's behaviour on a synthetic corpus; test_shoalmark.py pins what was built here. A change ships with its check, and the check is shown to fail without the change. Every consumer-visible change gets a CHANGELOG.md entry — --vendor prints it to the repository that upgrades. This repository tracks itself: python3 shoalmark.py --next. How a change here is reviewed, what a miss costs, and how the Owner is spoken to are this repository's house rules — the Owner's signed answers of 2026-09-24, in AGENTS.md.

9. Branding the board

Four optional files, the same names in every place — the board is built from the places in order, the later one wins: tools/shoalmark/brand/, the organisation's that set the repository up (--vendor copies and pins it) · <tracker dir>/brand/, the repository's, never loose among the trackers · ~/.config/shoalmark/, the person's, in every repository. Only the git-ignored board reads them: INDEX.md and the gate are the same whoever runs them.

• --brand says which place gave the board its theme, logo, wordmark and labels; --brand DIR writes a commented starter. The name is name in shoalmark.toml. A theme hard to read is a warning; status colours keep their meaning.
• Two themes ship as starters in the tool's brand/themes/, monochrome and shoalmark, each a theme.css with its fonts; --vendor copies and pins them, so a vendoring repository receives both. None is worn until --brand DIR --from <theme> copies it into a place: a board that chooses none looks as it did. A theme styles three hooks: the Owner's box's title #p>.pt (label owner.title), the last line #F (#f, #r), tr.zebra.
• Light and dark: dark colours go under @media (prefers-color-scheme:dark); ◐ (auto → light → dark) switches that rule for any theme and remembers the choice in the browser; paper stays light. A wordmark in currentColor takes the page's ink, at its height, else 22 px. Every page ends in the tool's line: its mark, name and version.
• Another language: labels.yaml for the board's words; [headings] in shoalmark.toml for the gate's sections.

Licence

Apache-2.0 OR MIT, at your option — LICENSE-APACHE, LICENSE-MIT, NOTICE. The one bundled file, vendor/marked-18.0.13.umd.js, is MIT. All three ship in a vendored copy.

What it is not, on purpose: no sprint, no estimate, no assignee, no comment thread, no editing in the board. A viewer, not a Jira.