5.1.0 — INDEX.md tells you what's next

INDEX.md was always a decent inventory. Three tables of what exists, with the choice of what to work on left to you or your agent.

The rule behind that only read the Active and Deferred tables. Once every spec named in decomposition.md was complete it called the roadmap finished, never reaching the "Other specs" table below, where every spec added after decomposition lives. One project had three specs in flight, all three in that table, one of them open on screen at the time, and INDEX.md still said there was nothing left to do.

INDEX.md now opens with a ## Next section naming one spec and the reason, mirrored in the spec-index result as routing. When it can't tell (two half-built specs, no declared order) you get both candidates and a stop instead of a guess. When everything is finished it says every spec on disk is complete rather than that the roadmap is done, because decomposition.md routinely names the next spec before its directory exists. That gap is the whole bug.

Two smaller fixes. A spec on its last task read as not-yet-implementing, so interrupting a run at the wrong moment left the document loop and the implementation loop each waiting on the other; resuming works now. And unreadable open checkboxes in a tasks.md now warn instead of counting for nothing.

After updating, run spec-index once with action: generate in each project. INDEX.md is written to disk rather than computed on read, so your existing file keeps its old shape until something rewrites it.

---

Added

• ## Next section in INDEX.md, mirrored in the spec-index tool result as routing. It publishes a state rather than a bare spec name, because the ways there can be no spec to work on are not interchangeable:
  • active — work on routing.spec.
  • ambiguous — several unsequenced specs qualify and nothing declares their order. Names the candidates and stops instead of guessing.
  • all-on-disk-complete — every spec on disk is Complete. Deliberately not "roadmap complete": INDEX.md is built by scanning .spec-workflow/specs/, and specs are created lazily, so decomposition.md routinely names the next spec before its directory exists.
  • all-deferred — specs exist but all are deferred. Nothing is complete.
  • no-specs — nothing exists yet.
• routing.warnings flags specs whose tasks.md holds still-open checkbox lines the task parser dropped (a task needs a leading number). Completed unparsed lines are not counted — the common - [x] Task 3 — ... "Implementation log" convention is a record of finished work, not a gap in the counts.
• parseTaskProgress now returns inProgress and unparsed alongside total, completed and pending.

Fixed

• A spec on its last task derived ready-for-implementation instead of implementing. A task is marked [-] before work starts on it, so the final task leaves pending: 0 with completed: total - 1 — matching neither branch and falling through. Anything other than implementing routes to the document loop, which finds all documents approved and hard-stops back to the implementation loop; interrupting a run on its last task made the two ping-pong.
• The residual bucket is no longer ranked by creation time. ## Other specs is sorted by directory birthtime, which git does not store and which any fresh clone or git worktree add restamps. Routing now considers only whether a spec has been started, and where that does not single one out it returns ambiguous.

Changed

• Progress no longer competes with declared build order. Within ## Active the first not-Complete spec still wins outright, because first-mention order in decomposition.md is a human-declared dependency sequence. Started-vs-not-started is used only in the residual bucket, which has no declared order at all.
• sdd-router.md, spec-loop-v3.md and task-implementation-loop-v2.md (maintained outside this repository) should branch on ## Next. The prose rule stays as a documented fallback rather than being deleted, since those files take effect on save while this server ships through npx @latest.

Full changelog: https://github.com/madmatt112/spec-workflow-mcp/blob/main/CHANGELOG.md