backlog@0.1

Grammar

[email protected] is [email protected] with three additions and nothing else: an extended marker enum, a reserved band vocabulary, and a blocker relation. Everything not below is todo’s grammar verbatim. Distilled for this page; the normative text is specs/backlog/SPEC.md, and it is the one that governs.

A conforming file begins with YAML frontmatter naming exactly one spec. The envelope, never the filename, is authoritative — .backlog.md aids discovery and nothing more.

---
markdownto: [email protected]
title: Tidepool            # optional, reserved
id: tidepool-backlog       # optional, reserved
bands:                     # optional, spec-defined
  - Commissioned
  - Drafting
  - Done
---

markdownto

Required. The exact string form [email protected]. A sequence or mapping here is MDTO004.

title, id

The reserved keys from the shared conventions. Optional, both strings.

bands

A sequence of strings, and the only key this spec adds. It replaces the reserved vocabulary rather than merely checking it: the declared names become the complete vocabulary and the declaration order becomes the priority order. A wrong type is MDTO007.

anything else

An unknown key: parsed, preserved, written back verbatim, never validated. This is what lets an agentsFS page carry description: and agentsfs_role: backlog in the same frontmatter block as the envelope and lose nothing on round-trip.

A level-2 heading is a band. With no bands: declaration, a backlog’s bands are exactly these five names, in this priority order — and any other ## heading is MDTO401.

## Now

Rank 0. Being worked, or next to be picked up.

## Next

Rank 1. Committed, not started.

## Later

Rank 2. Real work, not yet scheduled.

## Someday

Rank 3. Parked. Never offered as ready work — ideas kept rather than lost.

## Done

Rank 4. Closed. Holds terminal tasks and is safe to prune, which is the one thing reserving the name buys.

There is no implicit band. A backlog is a partition by priority, so a task in no band has no priority: a task above the first ## is MDTO406, and the repair is a heading, never an invented inbox. Prose before the first band is normal and legal — most backlogs open with a legend explaining their own markers. A backlog may also have no bands at all: an empty backlog is a real state, and a file should not have to carry a ceremonial heading to be one.

Empty bands may be omitted and may be written out empty; both are correct and neither is a diagnostic, even when the document declares bands:. Heading levels 3 and deeper are not part of the spec (MDTO405): nesting breaks a task down, headings group bands, and there is no third mechanism. A band heading carries no metadata — an inline field or block identifier on one is MDTO407. Task order within a band is priority order, top highest, and nothing sorts it.

A task is a GFM task list item on a bullet list, and [email protected] declares its full marker enum. [/] and [-] are what people already type in backlogs in the wild: they keep the file scannable, because the left edge of the line tells you everything.

- [ ] Ship a proper icon
- [/] Cache the tide tables so the app works offline
- [x] Pick a tide-data source with a licence we can live with
- [-] Rewrite the parser in Rust [reason:: the Swift one is already fast enough]

[ ]

open. Not terminal.

[/]

in-progress. Not terminal — and active rather than ready, which is why a tool offers it first.

[x], [X]

done. Terminal.

[-]

dropped. Terminal. A different outcome from done, and the same fact for everyone downstream: nobody is waiting on this any more.

anything else

The shared MDTO031, whose message names backlog’s enum rather than todo’s. Every tool must preserve an unrecognized marker character verbatim rather than coerce it to open or checked.

[reason:: …]

The one inline field this spec promotes to a recognized key. Free text, no diagnostic of its own, meaningful on any task — so a parked idea can record why it is parked. It is what drop --reason writes.

A task may end with a blocker clause saying what it is waiting on: a space, an em dash, a space, the words blocked by matched case-insensitively, a space, and then a non-empty comma-separated list. The clause stays part of the task’s text, like a tag and unlike a field, because it reads as part of the sentence and a plain Markdown viewer has no other way to show it.

- [ ] Home-screen widget showing the next high tide — blocked by [[#^offline-cache]] ^widget
- [ ] Submit to the App Store — blocked by [[#^dst-bug]], [[#^icon]] ^submission
- [ ] Ship a proper icon — blocked by Marina's illustration ^icon

[[#^slug]] found

Resolves in this file, and lifts itself the moment the target task reaches [x] or [-]. Keying on terminal rather than on done is what stops a dropped task silently deadlocking everything behind it.

[[#^slug]] missing

MDTO411. It names no block identifier in this file, so it can never lift; the repair is to fix the reference.

[[Name#^slug]]

External, and out of validation scope in 0.1 deliberately. Validation is a single-file parse that performs no I/O, so a claim about a file it has not been given is recorded and reported, never diagnosed. Do not “fix” a cross-file blocker by deleting it.

prose

First-class and expected. “blocked by Marina’s illustration” is more honest than inventing a task to point at. It holds until an author edits it away.

a cycle

A permanent block, reported once per member as MDTO415. A task that blocks itself is the one-member case.

A task is blocked when it has at least one blocker that is not satisfied. Nothing is scanned inside code spans or fences, so a file can document this clause without writing one. [[Name#^slug]] is always external even when Name is this file’s own name: the envelope and never the filename is authoritative, and a parser may have been handed a string rather than a path. Inside a backlog write [[#^x]]; from other files write [[backlog#^x]].

The band vocabulary only means something through this derivation, so it is normative for any tool that offers what should I pick up. A task is ready when all three hold.

state

It is open. A task that is in-progress is active, not ready — and active work is offered first.

not blocked

Every blocker it declares is satisfied. A broken relation counts as blocked, never as clear.

band

Its band is neither Someday nor Done. Everything else ranks: Now before Next before Later, and within a band, document order.

A child of an open parent is itself ready — decomposition means the children are the work. And a parent that is terminal while a child is not is MDTO420, a warning rather than an error: the file is unambiguous, it says exactly what it says, and validation is advice. The verbs are the strict half. finish and drop refuse rather than guess.

Read [email protected] in full — the normative text Shared conventions

Diagnostics carry the repair

Three of the findings below exist because the failure they describe is silent: the author believes a task is blocked and a tool believes it is ready. A file can look completely ordinary and be wrong in exactly that way, so the messages quote the offending element back, name what it actually parsed as, and say which direction to repair it in.

---
markdownto: [email protected]
title: Tidepool launch
---

## Now

- [ ] Ship the home-screen widget — blocked by
- [ ] Wire up the settings screen — blocked by [[#^onboarding]]
- [ ] Write the App Store copy — blocked by [[#^screenshots]] and the new icon
- [ ] Record the demo video, blocked by [[#^copy]] ^screenshots
- [ ] Draft the release notes — blocked by [[#^launch]] ^copy
- [ ] Book the launch tweet — blocked by [[#^copy]] ^launch

## Done

- [x] Pick a tide-data source — blocked by [[#^copy]]

MDTO400–MDTO499 belongs to [email protected], in three families: bands in 401–409, the blocker relation in 410–419, state and hierarchy in 420–429. Codes are never reused, renumbered or repurposed. Everything else a backlog file can get wrong is a shared code — and MDTO031, the unrecognized marker, is shared and not owned here: the same broken marker produces the same code in every spec, and only the message names this spec’s enum.