Map format¶
The format contract¶
The contract is the skill's local-markdown adapter, TRACKER-MARKDOWN.md; the skill itself is tracker-agnostic method.
This tool implements that adapter, and any other reader should target the same file.
In summary: structure the facts, leave the prose alone. A ticket's type and edges have exactly one correct value a machine can check. Its Question and Answer, the map's Destination and Notes, and each one-line gist in Decisions-so-far are lossy prose, never parsed.
A ticket is .plan/<effort>/tickets/NN-<slug>.md:
---
type: research | prototype | grilling | task | implement
blocked_by: [02, 03] # [] when none
claimed_by: <session id> # while a session holds it
claimed_at: 2026-07-10T09:00:00Z # RFC 3339, alongside claimed_by
undermined_by: [08] # optional, resolved on a premise 08 later broke
assets: [../assets/x.html.approved] # optional
pr: https://github.com/o/r/pull/12 # optional, implement only
afk: true # optional, task only: an agent can drive it alone
---
# <Ticket title>
## Question
...
## Answer # its presence _is_ the resolution
...
An implement ticket swaps Question for What to build plus - [ ] acceptance criteria, targets one repo and usually one PR, and resolves when the work has shipped.
Its Answer records what shipped and links the PR or commit when there is one.
The map indexes it under Implemented so far, the counterpart of Decisions-so-far, see Implement tickets.
Research and implement tickets are AFK (an agent can take them), grilling and prototype are HITL, and a task is HITL unless it sets afk: true.
Status is derived¶
There is no status: field: every value it could hold is already written in the file, and a second copy is free to go stale.
| Derived status | When |
|---|---|
resolved |
the body has an ## Answer with prose under it |
out_of_scope |
the body has a ## Ruled out with prose under it |
claimed |
neither, and claimed_by is set |
open |
none of the above |
Closure is read first, so a claimed_by left on a closed ticket is inert litter.
And it is the prose, not the heading, that closes a ticket: a session that types ## Answer and dies has resolved nothing.
The ticket stays claimed, and its claim goes stale on schedule.
lint errors on the empty heading outright.
undermined_bymarks a decision whose premise a later ticket broke; without it a renderer paints the node green and launders a live problem into a checkmark.claimed_atseparates a dead session from live work.out_of_scopestays distinct fromresolved: a scope boundary is not a step on the route, and a parser that lumps them in over-counts.
Fenced code blocks are not structure¶
Every scan (headings, titles, bullets, links) ignores what sits inside a ``` or ~~~ fence.
A ticket that quotes the ticket format contains the line ## Answer, and must not thereby resolve itself.
The rule cuts one way only: an answer whose entire body is a code fence is still an answer.
Any other reader of these files owes the same rule.
One session at a time¶
The adapter forbids concurrent sessions: git merges a duplicate ticket number cleanly and neither session can see it.
lint still reports duplicates, because a merge can happen anyway.
Fog¶
Fog patches in the map's ## Not yet specified are bullets with a bolded lead title and an optional anchor; the rest stays loose prose:
- **Today's row.** Whether today is visually distinguished. <clears-with: 04>
Checks¶
lint reports errors and warnings, and exits 0 clean, 1 errors found, 2 no map at that path.
Errors:
- dangling or self
blocked_by, andblocked_bycycles; - duplicate ticket numbers;
- a ticket carrying both
## Answerand## Ruled out, or a closing heading with nothing under it; - a resolved ticket missing from Decisions-so-far (Implemented-so-far for an implement ticket);
- an out-of-scope ticket listed as a decision or implemented, or missing from Out-of-scope;
- Decisions-so-far or Implemented-so-far pointing at an unresolved ticket;
- a fog patch duplicating a live ticket's title, or anchored to a resolved ticket;
- a missing Destination, or an unknown type;
- a leftover
status:field that disagrees with the body; - a
prthat is not a single http(s) URL.
Warnings:
- loose (pre-frontmatter) headers, and a
status:field that merely duplicates the body; - a claim with no owner or older than 72h, or a claim left on a closed ticket;
- a ticket blocked by something out of scope, which can never unblock;
pron a non-implement ticket, orafkon a non-task ticket;- an implement ticket in Decisions-so-far, or any other ticket in Implemented-so-far.
Checks that need judgment (does a gist say what its answer says, does a fog title duplicate a live ticket in substance) stay with the skill; no parser can make them.
Reading legacy maps¶
Two older shapes still parse, each lints as a warning, and neither is written any more:
- the loose header (
Type:/Status:/Blocked by:after the H1), from before frontmatter; - a stored
status:field, from before status was derived. Where it agrees with the body,lintsays to delete it; where it disagrees, that is an error and the body wins.