issuegraph:

Standard YAML frontmatter. Any tracker can store it, any parser already reads it. Nothing is installed and nothing is migrated.

If a body somehow ends up with two frontmatter blocks, the first one containing an issuegraph: key is the real data. Later ones are ignored, so a bot's banner or a wrapper can't quietly override what you wrote.

Write it plain, exactly as above. Some trackers garble bare frontmatter when they render it — GitHub, for one, draws --- as a horizontal line and turns the line above it into a heading. For exactly that case, the spec explicitly permits wrapping the block in a normal triple-backtick code block — it is a sanctioned part of the format, not a workaround. It changes only how the block looks on screen: the text inside is byte-for-byte identical, it stays portable between trackers, and readers look straight through the wrapper to find it.

An issue with no issuegraph frontmatter is still valid — it just has no edges and default priority. You add fields where you actually know something.

decomposed-from only records where an issue came from. It has no effect on ordering. There are no parent issues and no container issues: an issue that got split closes as soon as the split is done, and “what came out of #230?” is answered by asking the graph, not by a tracking issue someone has to keep tidy.

evidence is the odd one out — it changes no ordering at all. It says whether whoever wrote the issue actually verified its claims or just asserted them. Machine-filed issues are frequently wrong in small ways, and splitting an unverified issue produces a whole subtree of work built on a false premise, so the next worker wants to know before building on it. It earns its place by protecting decomposition, which is what produces the relationships in the first place.

You never write the group down. serialize-with and together-with both describe a set of issues, but no issue ever holds the list. To join, point at any one issue already in the set — it does not matter which. The reader follows the links and works out the full set for you.

#232 writes serialize-with: 231  ·  #233 writes serialize-with: 232  ·  #234 writes serialize-with: 231
→ the reader sees one group: { 231, 232, 233, 234 } — and only one of them may run at a time.

This is the part that stops it rotting. To leave a group you delete your own field, and nothing else. Closing an issue never means going back to edit the others. No issue ever writes to another issue's body, and there is no membership list anywhere that can drift out of date — the usual way this kind of bookkeeping dies. One line per issue, and nothing to maintain.

If you accidentally link two groups they merge, which costs you some parallelism and never costs you correctness.

ready — the issue is open, every issue in its blocked-by has closed, and nothing in its serialize group is being worked. Anything not ready is invisible to selection: a scheduler cannot pick it up, so nobody has to protect it.

effective priority — the highest declared priority among the issue itself and every open issue that depends on it, however far down the chain. Readers select by this, not by the number written on the issue. That is why #233 above shows P2 → 1: it is a P2 holding up a P1.

parallelism — two ready issues with no path between them can be worked at the same time. Nothing else needs to say so.

Where the line is. Issuegraph records what the work is and what it depends on — things that stay true no matter who or what picks it up, or how many times they try. Anything describing a particular attempt at the work belongs to the thing making the attempt.

The one-question version: if you had a flawless scheduler, would it still need this written on the issue? If it could work the answer out for itself, or get along fine without it, the field stays out. “Is #232 blocked?” it cannot possibly guess — that's a fact somebody knows. “Is anyone working on #232 right now?” it already knows, because it's the one handing out the work.

The reason to be strict about this: the moment a format starts carrying run state, it's welded to whichever tool wrote that state, and it stops being portable — which was the whole point.

Every issue is a piece of work. Issuegraph has no issue kinds — no PM issues, no tracking issues that exist only to hold other issues, no standing checklists, no issues used as a log. An issue is either small enough to work, or the only thing you may do to it is split it, and the split closes as soon as the smaller issues exist. That is what stops the graph filling up with nodes nobody will ever finish.

So where do those issues go? They stay in your tracker, and the spec says nothing about them on purpose. Readiness is the graph's answer to “may this start?”; whether a reader is willing to pick something up is the reader's own business, layered on top. Filtering by label is the normal way to do it — tag your standing checklists meta, your discussion threads rfc, and have your reader ignore those labels. Issuegraph never learns why you skipped them, and no field is added to describe it.

The same 48 issues, two orderings. Order by newest is the backlog as a tracker shows it — newest first, read left to right. Order by issuegraph is the same 48 issues arranged by what their frontmatter already says — blockers above, dependents below, edges drawn between them. Nothing was added to get from one to the other.

Then play it — whack-a-mole, two rounds. The reader deals the backlog in waves: everything ready lights up at once — one to four issues, your pick — holds for a blink, then the board rests before the next wave. Whack what you can while it shows; whatever you miss closes anyway, because the frontier moves with or without you. Round 1 plays ordered by newest, where every wave lands somewhere you didn’t expect. Round 2 replays the identical waves ordered by issuegraph, where every closure points at what it frees up next. The sequence never changes; only your ability to see it coming does.