The spec and the trail
The spec states what the work holds now. The trail keeps how it got there. Between them, a companion can change a commitment everywhere it is carried, and read why it was made before it does.
The problem it was built for
A claim stated in one chapter gets restated in another, and the restatements drift. Each one reads well where it stands. Together they disagree, and nobody notices until a reader does. It happens to a long argument, a history, a site whose posts lean on one another: anything that has to stay consistent with itself while it grows.
The listings on this page are real output, run against Side Quest, the sample book in Quirework’s repository. The book is fiction that AI wrote to test the tool, and no person reviewed its prose. The examples page says more.
A file of commitments
The spec is one Markdown file. Each commitment is a level-two section, and its heading carries a slug, a short permanent name. This one, from the sample book, is a commitment a check enforces:
## Em's dashes stay off the page {#em-dashes-off-the-page}
The prose contains no em dash anywhere, so Em's are counted and never
shown. A message from Em is reported or paraphrased, never quoted with
its punctuation intact. The book says why in its own terms: it has
promised not to, and the software is checking. The word "spec" never
reaches the reader.
A chapter never restates a commitment. Its notes name the section it expresses, and that name is the whole mechanism: change the section, and the names lead to every chapter that has to change with it.
The spec states and does not argue. It holds no dates, no review rounds, and no account of what a section used to say. A dated ruling reads as authority to the next session, which then works around the section instead of proposing a change to it.
A session starts by reading it. quirework spec notes --primer prints
the spec’s sections first, then each chapter’s notes in reading order.
quirework spec notes --primer
spec — manuscript/sections/_spec.md (shared; 12 section(s); read it before the marks):
#side-quest The side quest is the subject [trail ×2]
#claims-in-sentences Claims that lived only in sentences [trail ×4]
#two-shops Two shops, one habit [trail ×3]
#notes-escalate The notes escalate [trail ×3]
#worth-what-you-check An assistant is worth what you can check [trail ×5]
#the-name The name came from "quire" [trail ×6]
#no-villains No villains [trail ×3]
#em-never-asked Em is never asked [trail ×4]
#em-dashes-off-the-page Em's dashes stay off the page [trail ×2]
#people-who-ask The people who ask about the book [trail ×9]
#not-the-book-it-was-built-for The tool is not the book it was built for [trail ×4]
#written-with-the-tool Written with the tool it is about [trail ×5]
12 of 12 section(s) have a trail of the sessions that shaped them: quirework spec trail SLUG
manuscript/sections/preface.qmd — Preface (4)
marks: manuscript/sections/_marks/preface.md
------------------------------------------------------------
L8 @guidance shorter than a chapter; admits the book is written with the tool, and says once, in one flat sentence, that the names are changed and everything that deserved it is exaggerated
L11 @guidance "I fixed most of them" stays: Cy stands behind the book not claiming to be fully consistent
L13 @bind(written-with-the-tool) [trail ×5]
L14 @bind(side-quest) [trail ×2]
lines left out
Notes beside the prose
Each chapter has a sidecar, a Markdown file whose headings mirror the
chapter’s. It holds the chapter’s marks. A @bind names a commitment
the chapter carries. A @guidance says how the chapter should read.
Other marks hold open work, counts that must stay true, and quotations.
Here is the start of one chapter’s sidecar in the sample book:
# The Name {#sec-the-name}
<!-- @guidance the irony of who named the tool is left for the reader to
find: "quire" is the page's last line and the word Cy types, Otto
only finishes it, and Cy likes the result better than anything on
the page, and nothing after it explains the joke. "For a year I
told people Otto named it. Then I found the page." comes right
after Otto's word, once, and nothing explains it -->
<!-- @bind(the-name) -->
The marks never touch the prose. The rendered book carries none of them, and reflowing a paragraph never moves one. The prose stays the prose, and the notes about it stay findable.
One commitment, everywhere it is carried
spec notes bind --slug lists every unit that binds a commitment. A
derived edition binds the same spec, so a commitment can be followed
from the chapter that states it into every edition that retells it. An
edition that leaves a commitment out says so with an @omit mark and a
reason.
quirework spec notes bind --slug the-name
@bind (4)
------------------------------------------------------------
manuscript/sections/_marks/the-name.md:14 [sec-the-name]
(the-name) [trail ×6]
variants/poems/_marks/the-name.md:43 [sec-the-name]
(the-name) [trail ×6]
variants/six-pager/_marks/memo.md:67 [sec-otto]
(the-name) [trail ×6]
variants/young-readers/_marks/the-name.md:16 [sec-the-name]
(the-name) [trail ×6]
total: 4 mark(s) across 1 kind(s)
A slug can outgrow its name. It is written in the spec, in every sidecar
that binds it, and on the trail. quirework spec rename OLD NEW renames
it in all of them, or refuses before writing anything.
What the checks catch
spec notes --check gates thirteen invariants of the structure. Among
them: a mark left in the prose, a sidecar that no longer mirrors its
chapter, a binding to a commitment the spec does not declare, and a
reading order that disagrees with the files on disk. spec quotes
checks that a phrase quoted in a note still exists in the work, and
spec quotes --grep TERM finds every quotation of a term you have just
retired.
quirework spec units --check
✓ units --check: 12 chapter(s) in reading order, every @unit() resolves.
quirework spec notes --check
advisory (1 contract mark(s)/spec section(s) carry decision-journaling; current state, never history — the story belongs in git):
manuscript/sections/_marks/back-cover.md:8: @guidance — '2026-10-09'
✓ notes --check: sidecar layout clean.
quirework spec trail --check
✓ trail --check: 50 breadcrumb(s) in provenance/spec-trail.md.
Research gets a register of its own. Each source has a slug, and a mark
cites it as @source(slug). spec sources --slug S lists every chapter
that leans on a source, and the check refuses a citation of a source the
register does not hold. A source can keep a plain-text capture of
itself, and a quotation from it is checked against that capture. A
misremembered line is caught the way a misquoted chapter is.
The trail
A spec section says what the work holds. The words you used in June and the sharper ones from last week say how it got there, and whoever changes the section next should read them. The trail keeps that story outside the spec, in a sidecar of its own, kept with your private material. Under each section’s heading it lists breadcrumbs. A breadcrumb names a conversation, the moment in it when you shaped the section, and what that turn did:
- seed: first stated what the section holds
- sharpen: made it more precise
- correct: refused a wording the companion proposed
- reverse: moved off an earlier position
- accept: took a wording the companion drafted
- probe: tried something without settling it
A breadcrumb is a pointer, never a copy. It names a session and the time the harness logged your turn, which anyone can find again, with Quirework or without it. Your words are read from the session itself whenever the trail is read, and the command to open each turn is printed beside it.
quirework spec trail the-name
#the-name — The name came from "quire"
bound by: the-name
6 breadcrumbs from 3 sessions, 2026-10 · seed 1 · sharpen 3 · correct 1 · reverse 1
2026-10-09 1b7ad009 seed Human 3
note Otto completed quirk as quirework.
opens Here's the story, roughly in order. Everyone's name is changed, and I've exaggerated everything that deserved it. Full Stop is a natural history of punctuation: where each mark came from, and who spr…
read quirework provenance show 1b7ad009 --turn 3
2026-10-09 1b7ad009 correct Human 4
note Cuts the drafted line on who named the tool; the reader finds that irony alone.
opens Good draft. Answers in your order. 1. Keep "counted, never shown". It's the best rule in the spec and I didn't write it, which I'll be annoyed about later. 2. Cut "The tool that exists to check an as…
read quirework provenance show 1b7ad009 --turn 4
lines left out
2026-10-09 c137540e reverse Human 1
note Reverses the seed and the sharpen: Cy remembered typing "quirk" to ask Otto something else, and Otto making the name. The page of names from that evening, found later, ends in pencil at ten to two on "quire", the folded gathering of pages a book is sewn from; at two Cy typed "quire" and Otto finished it as "quirework". The name came from "quire": Otto finished a word Cy had already chosen.
opens Something in chapter five is wrong, and it's my fault. Last night I went looking for the shoebox with the radiator card and found the page of names from that evening instead. The last line on it, in …
read quirework provenance show c137540e --turn 1
lines left out
The trail is context, never authority: the spec states what the work holds now, and a request made now outranks anything on it.
spec trail prints it. Each breadcrumb shows the note the companion wrote, how the author’s turn opened, and the command that opens it. The author is invented: an AI wrote every one of the author’s turns.The trail is written while the spec is edited. When your words in the
current conversation change what a section holds, the companion adds a
breadcrumb in the same session, because it is the one reader that knows
which words did it. It errs toward including one, since a reader can
skip a breadcrumb but nobody can recover a turn that nobody pointed at.
A breadcrumb is never deleted because you moved on. A reverse is added
instead, because the earlier position is part of the story.
The trail is context, never authority. The spec states what the work holds now, and what you ask for now outranks anything on the trail.
Backfilling a trail
A spec that grew before it had a trail needs its history read, and
hundreds of sessions are too much for a strong model to read whole.
spec trail backfill splits the work by what it costs. Cheap readers go
through each session once and flag every turn of yours that might have
shaped any section. A strong model then takes one section at a time,
reads everything flagged for it, oldest first, and decides. Each session
is read once against the whole list, because reading it costs the same
whether it is read for one section or for all of them.
The authoring guide walks through a spec, its marks and its trail from an empty directory.