Roadmap Tool

bbox_roadmap is a prospective work tracker: designed-but-not-implemented features, refactors, explorations, tech debt, and risks. It sits in a distinct time band from the other stores - inbox is reactive, threads are active, knowledge is atemporal. The roadmap tracks the future.

The blackbox project roadmap is the generated output of this tool applied to this repo. This page explains the tool itself.

Item model

Each roadmap item has:

Field	Values
status	proposed → accepted / rejected; accepted → deferred; deferred → accepted; rejected → proposed
category	feature, refactor, exploration, debt, risk, infrastructure
priority	high, medium, low
scope	global or project (project-scoped requires project path)

Items also carry a transition history (who moved it, when, and why).

Edge kinds

Link items to related entities in the corpus:

Kind	Purpose
designed_in	Design doc that fully specifies the item
spawns	Work thread opened when the item was promoted
deferred_from	Thread or event that caused the deferral
depends_on	Another roadmap item this one needs first
blocked_by	Entity (task, thread, decision) blocking progress
supersedes	Item this one replaces
subsumes	Item absorbed into this one
related_to	General cross-reference

Actions

create

Add a roadmap item. Starts in proposed status.

bbox_roadmap(
  action="create",
  title="Disk-backed WaitStore",
  body="Suspended arcs lose their wait registrations on daemon restart. Persist to disk.",
  category="infrastructure",
  priority="high",
  scope="project",
  project="/repo/x"
)

Duplicate guard: returns {duplicate: true, existing_id: ...} if a title match already exists.

get / list / search

bbox_roadmap(action="get", id="rm-a1b2c3d4")
bbox_roadmap(action="list", project="/repo/x", status="accepted")
bbox_roadmap(action="search", query="wait store", category="infrastructure")

update

Change title, body, status, category, or priority. Status transitions are validated against the allowed graph.

bbox_roadmap(action="update", id="rm-a1b2c3d4", status="accepted", priority="high")

next

Rank accepted items by priority, staleness, and design-link health. The primary planning surface: tells you what to work on next.

bbox_roadmap(action="next", n=5, project="/repo/x")
bbox_roadmap(action="next", n=10, include_blocked=true)

Items with a designed_in link rank higher (the design already exists; implementation is the remaining step). Items with blocked_by edges are filtered out unless include_blocked=true.

promote

Spin an accepted roadmap item into an active work thread. Injects the item's body and design links as the thread's context.

bbox_roadmap(action="promote", id="rm-a1b2c3d4", project_dir="/repo/x")
bbox_roadmap(action="promote", id="rm-a1b2c3d4", brofile="executor", project_dir="/repo/x")

Returns the opened thread_id and a spawns edge linking the item to the thread.

link / unlink

bbox_roadmap(
  action="link",
  id="rm-a1b2c3d4",
  link_type="designed_in",
  link_target="knowledge:ab12cd34",
  link_note="Phase 1 of design/commit-work-provenance.md"
)
bbox_roadmap(action="unlink", id="rm-a1b2c3d4", link_type="depends_on", link_target="rm-efgh5678")

repair_links

Validate all edges for an item (or the full store). Reports dangling references - designed_in pointing to a deleted knowledge entry, spawns pointing to a resolved thread, etc.

bbox_roadmap(action="repair_links", dry_run=true)          # full store
bbox_roadmap(action="repair_links", id="rm-a1b2c3d4")      # single item

render

Emit the roadmap as markdown, grouped by status and sorted by priority. The output is written to the docs/roadmap.md file (or a custom path via write_path).

bbox_roadmap(action="render")
bbox_roadmap(action="render", write_path="/tmp/roadmap-draft.md")

The generated file carries a <!-- Generated by blackbox --> header. Do not edit it by hand - changes are overwritten on the next render.

delete

Remove an item and all its edges.

bbox_roadmap(action="delete", id="rm-a1b2c3d4")

Typical flow

# Propose an item
bbox_roadmap(action="create", title="...", body="...", category="feature", ...)

# Accept it and link its design doc
bbox_roadmap(action="update", id="rm-...", status="accepted")
bbox_roadmap(action="link", id="rm-...", link_type="designed_in", link_target="knowledge:...")

# Decide what to work on
bbox_roadmap(action="next", n=5)

# Start a thread and code
bbox_roadmap(action="promote", id="rm-...", project_dir="/repo/x")

# Regenerate the published roadmap page
bbox_roadmap(action="render")

Storage

Items persist to ~/.local/share/blackbox/roadmap.json (path follows BBOX_DATA_DIR if set). The store is a flat JSON array - no external database.