CLI command
jeden roadmap
Read and transactionally mutate the repository-owned Jeden roadmap.
Exact invocation#
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 nfor optimistic concurrency; without it they use the snapshot that invocation read, and still fail if another writer commits first. Pass--revisionin automation. - Statuses are
backlog,planned,in_progress,implemented,not_run,failed,external_blocked,passedanddropped.passedrequires evidence andexternal_blockedan 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/roadmapopens 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-onand--external-prerequisiteflags. - 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/<ID>.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
--revisionis 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 exit1:header-unreadableandheader-invalid(roadmap.yamlmissing, unreadable or not the roadmap's YAML),forms-mixed(aroadmap.yamlholding items or context besideitems/orcontext.md),parts-unlistable,part-unreadable,part-invalid,part-misnamed(a part not named<ID>.yamlfor the upper-case id it holds),context-unreadable,id-unnameable(an id with a path separator,.or..),unencodableanditems-uncreatable. A part that cannot be replaced keepsjeden.file.replace's cause with the linecontext: writing the roadmap's <part> to <path>; the parts written before it hold the change androadmap.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) exits69; any other refusal or failure exits1. A refusal a functionality declares ends withfix: …andcause: <operation>.<cause>, andjeden errors show <operation>lists every cause of that functionality.