Cartographer

draft 1.0.0
  status candidate
  title Cartographer Specification
  date 2026-04-30
  license All Rights Reserved

---

spec cartographer

  section purpose
    title Purpose
    level 1

    prose
      value
        Cartographer is a tree-based format and reference parser
        for roadmaps and project plans. Plans are written in a
        Draft-like indentation syntax; the parser produces a
        typed AST that downstream tools render as tree or
        sequence views. The byre.dev /roadmap page is a live
        demonstration: it renders this very repository's master
        plan.

  section primitives
    title Primitives
    level 2

    prose
      value
        A cartographer document is a tree of nodes addressed by
        keyword (roadmap, goal, task, criterion, note, item,
        risk, concern, convention, description, include). Each
        node has a title and may have children. Goals and tasks
        carry id and status.

    requirement K-001
      level MUST
      value
        Node ids MUST match the regex /^[A-Z]+-[0-9]{3,}$/.

    requirement K-002
      level MUST
      value
        Within a sibling group, the source-order of tasks MUST be
        the execution order. Reordering siblings in source
        reorders the rendered sequence view.

  section status
    title Status semantics
    level 3

    prose
      value
        Cartographer recognises a fixed status palette:
        proposed (work not yet started), active (currently in
        progress), done (completed), blocked (waiting on
        something external), archived (intentionally retired).

  section composition
    title Composability via include
    level 4

    prose
      value
        Long plans are decomposed across multiple files using the
        include directive. The parser resolves includes lazily so
        each file remains independently parseable.

    requirement K-010
      level SHOULD
      value
        Plans larger than a few hundred lines SHOULD be
        decomposed across files via include, so per-iter or
        per-feature plans can be edited independently.