Jeden/Docs

CLI command

jeden roadmap

Read and transactionally mutate the repository-owned Jeden roadmap.

Exact invocation#

Shell
jeden roadmap <list|show|add|edit|drop|start|implemented|block|unblock|pass|status|depends|undepends|graph|acceptance|check|work> [args] [--json] [--cwd path]

Inputs and options#

  • Required for non-default use: one listed action; no action defaults to list.
  • Mutation leaves accept --revision n for optimistic concurrency; without it they use the snapshot that invocation read, and still fail if another writer commits first. Pass --revision in automation.
  • Statuses are backlog, planned, in_progress, implemented, not_run, failed, external_blocked, passed and dropped. passed requires evidence and external_blocked an external prerequisite; dependencies must resolve and stay acyclic, and capability IDs must exist in the capability registry.
  • The same operations are /roadmap … in a session. Bare /roadmap opens the searchable picker; its Add roadmap item row prefills an editable command holding the required title, area, priority, summary and acceptance fields. Dependencies and external prerequisites are repeated --depends-on and --external-prerequisite flags.
  • Use the linked leaf pages for action-specific identifiers, values, filters, reasons, evidence, and output.

Output and state effect#

Reads or updates the roadmap directory: roadmap/roadmap.yaml holds schemaVersion and revision, roadmap/context.md the context and roadmap/items/&lt;ID&gt;.yaml one item each, so no file of it outgrows the line cap. A roadmap.yaml that still holds the items or the context itself (every roadmap written before the parts) is read whole, and the next change writes it as parts. The roadmap read whole follows its machine contract roadmap/schema/roadmap-v1.schema.json. Every mutation is serialized through a stable sibling lock, validates the expected revision and the complete graph and status invariants, writes each part through a same-directory temporary file that is flushed, fsynced and renamed over it, writes roadmap.yaml with the incremented revision last, and appends roadmap event evidence. roadmap work also pins the session's later artifacts and branches to activeRoadmapItem.

Refusals and boundaries#

  • Unknown actions are refused with the complete expected command set.
  • A stale --revision is refused as a revision conflict; invalid schema, IDs, dependencies, priorities, statuses or evidence never commit a mutation.
  • Reading and writing the parts is jeden.roadmap.store (tests/roadmap/parts.mjs), each exit 1: header-unreadable and header-invalid (roadmap.yaml missing, unreadable or not the roadmap's YAML), forms-mixed (a roadmap.yaml holding items or context beside items/ or context.md), parts-unlistable, part-unreadable, part-invalid, part-misnamed (a part not named &lt;ID&gt;.yaml for the upper-case id it holds), context-unreadable, id-unnameable (an id with a path separator, . or ..), unencodable and items-uncreatable. A part that cannot be replaced keeps jeden.file.replace's cause with the line context: writing the roadmap's &lt;part&gt; to &lt;path&gt;; the parts written before it hold the change and roadmap.yaml, written last, still names the previous revision.
  • A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits 2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: &lt;operation&gt;.&lt;cause&gt;, and jeden errors show &lt;operation&gt; lists every cause of that functionality.