Skip to content

Map

Two layers sharing one git state. Pick the level that matches what you need to do.
🌳 evergreen tended 2026-05-08 orientation layers L0-L1-L2 
flowchart LR
  r[reader] --> rm[README]
  rm --> hum[human layer]
  rm --> proto[autonomous protocol]
  hum -.git.- proto
Read next

Three resolutions below — L0 (5 nodes) · L1 (layer detail) · L2 (full graph).

The canonical visual map of this repo. Same content, three resolutions. Pick the level that matches what you need to do.

Compress levels: L0 ↓ L1 ↓ L2

L0 — What is this? (1 diagram, 5 nodes)

flowchart LR
  reader[You] --> readme[README]
  readme --> human["Human-readable layer<br/>TODO · investigations · docs"]
  readme --> protocol["Autonomous protocol<br/>SWARM.md · tools/"]
  human -.->|git state| protocol
  protocol -.->|git state| human
  protocol --> runner["folder-runner<br/>local → remote"]

The repo is two layers sharing one git state. Humans read the human-readable layer. AI sessions follow the autonomous protocol. Both write to the same files; the runner lets a local machine trigger remote tool runs against any folder.

L1 — How the layers fit

Human-readable layer

Click any node to open the file. (Clickable on the website; on GitHub web view the click lines are shown verbatim — same source, two renderings.)

flowchart TB
  readme[README]
  todo[TODO]
  schema[Schema]
  rating[Rating]
  mmd[Mermaid]
  insp[Inspiration]
  invs[Investigations]
  this[Map]

  readme --> todo
  readme --> this
  readme --> invs
  todo -->|conforms to| schema
  todo -->|rated by| rating
  invs -->|use| mmd
  invs -->|cite| insp
  schema -->|defines fields used by| rating
  this -.indexes.-> readme

click readme "../../" "README.md"
click todo "../../tasks/TODO/" "tasks/TODO.md — rated, ordered tasks"
click schema "../../tasks/SCHEMA/" "tasks/SCHEMA.md — typed contracts"
click rating "../RATING-AND-PRIORITY/" "docs/RATING-AND-PRIORITY.md"
click mmd "../MERMAID-CONVENTIONS/" "docs/MERMAID-CONVENTIONS.md"
click insp "../INSPIRATION/" "docs/INSPIRATION.md"
click invs "../investigations/" "docs/investigations/ — six long-running questions"
click this "./" "docs/MAP.md (you are here)"

Six docs + one task list. Schema is the contract; rating drives ordering; investigations are the long-running questions; mermaid + inspiration are conventions.

Autonomous protocol (existing — captured for completeness)

flowchart LR
  start([Session start]) --> orient[orient]
  orient --> order[task_order]
  order --> ask[question_gen]
  ask --> dispatch[dispatch]
  dispatch --> act[act + diff]
  act --> compress[compress]
  compress --> sync[sync + validate]
  sync --> push[git push]
  push --> start

click orient "../../SWARM/#minimum-cycle" "tools/orient.py"
click order "../../SWARM/#minimum-cycle" "tools/task_order.py"
click ask "../../SWARM/#minimum-cycle" "tools/question_gen.py"
click dispatch "../../SWARM/#minimum-cycle" "tools/dispatch_optimizer.py"
click sync "../../SWARM/#minimum-cycle" "tools/sync_state.py + validate_beliefs.py"

This is what SWARM.md §Minimum Cycle describes in prose. Same content, scannable form.

Runtime / shared state

flowchart LR
  beliefs[("beliefs/")]
  tasks[("tasks/")]
  memory[("memory/")]
  domains[("domains/")]
  sessions{{"Sessions"}}

click beliefs "../../beliefs/CORE/" "beliefs/ — CORE · PHILOSOPHY · INVARIANTS"
click tasks "../../tasks/TODO/" "tasks/ — TODO · NEXT · FRONTIER · LANES"

  beliefs -->|inform| sessions
  tasks -->|coordinate| sessions
  memory -->|store knowledge| sessions
  domains -->|specialize| sessions
  sessions -->|commits update| beliefs
  sessions -->|commits update| tasks
  sessions -->|commits update| memory
  sessions -->|commits update| domains

Four state buckets. Sessions are the only verb; everything else is state.

Investigation page anatomy

flowchart TB
  page[Investigation page]
  page --> l0["L0: TL;DR<br/>≤5 lines"]
  page --> l1[L1: Overview]
  page --> l2[L2: Deep dive]
  l1 --> mmap["Mermaid map<br/>5–9 nodes"]
  l1 --> claims[Skeleton sub-claims]
  page --> oq[Open questions]
  page --> refs[References]
  page --> ins[Inspiration sources]
  page --> see[See also: lateral links]

Every page in docs/investigations/ follows this shape.

Folder-runner flow (local → remote)

sequenceDiagram
  autonumber
  participant Local as Local (gh CLI)
  participant GH as GitHub Actions
  participant Repo as Repo / git
  participant Tools as tools/
  participant Out as .runner-out/

  Local->>GH: workflow_dispatch<br/>(folder, tools, ref)
  GH->>Repo: checkout ref
  GH->>GH: validate schema.py imports
  loop each tool in input list
    GH->>Tools: run tool --folder <folder>
    Tools-->>Out: stdout / stderr
  end
  GH-->>Local: upload artifact
  Note over GH,Local: PR trigger also posts<br/>tail of each output as PR comment

L2 — Per-area detail

Task lifecycle

stateDiagram-v2
  [*] --> open
  open --> in_progress: claim
  open --> blocked: dependency missing
  in_progress --> blocked
  in_progress --> done: artifact shipped
  in_progress --> abandoned: scope dropped
  blocked --> in_progress: unblocked
  blocked --> abandoned
  done --> [*]
  abandoned --> [*]
  open --> abandoned: cancelled

Closed states (done, abandoned) freeze the record. New info goes to a successor task.

Investigation graph

Click any node to open the page.

flowchart LR
  stig[stigmergy] --> brain[brain]
  brain --> energy[energy]
  energy --> learn[skills]
  stig --> universe[universe]
  brain --> universe
  energy --> bureau[bureaucracy]
  bureau --> universe
  learn -.feeds.-> energy
  universe -.frames.-> stig

click stig "../investigations/STIGMERGY-IN-DAILY-LIFE/" "Stigmergy in daily life"
click brain "../investigations/BRAIN-MEMORY-MANAGEMENT/" "Brain memory management"
click energy "../investigations/ENERGY-AND-ATTENTION/" "Energy and attention"
click learn "../investigations/LEARNABLE-SKILLS-FOR-VARIANCE/" "Learnable skills for variance"
click bureau "../investigations/BUREAUCRACY-AND-AI/" "Bureaucracy and AI"
click universe "../investigations/UNIVERSE-EVOLUTION-AS-COMPRESSION/" "Universe evolution as compression"

Six pages, mostly forward-linked, two back-edges. The cycle through universe is intentional — it's the unifying frame.

Schema entity-relations

classDiagram
  class Task {
    id, title, rating, status
    created, due
    parents[], children[]
    artifacts[], refs[]
    priority_key()
  }
  class Artifact {
    kind: input|build|result|diff
    ref, when, note
  }
  class Investigation {
    id, title, rating
    levels: L0|L1|L2|...
    refs[], inspiration[]
    mermaid?, open_questions[]
  }
  class Lane {
    id, session, domain, intent
    expect, artifacts[]
  }
  class Lesson {
    id, title, session, domain
    rating, external_ref?
  }
  Task "1" o-- "*" Artifact
  Investigation ..> Task : refs
  Lane ..> Task : refs
  Lesson ..> Lane : produced by

Rating → ordering pipeline

flowchart LR
  pool([All open tasks]) --> bucket{rating?}
  bucket -->|bad| b[BAD: do first]
  bucket -->|medium| m[MEDIUM: do next]
  bucket -->|good| g[GOOD: do later]
  b --> dueb[sort by due]
  m --> duem[sort by due]
  g --> dueg[sort by due]
  dueb --> q([Queue])
  duem --> q
  dueg --> q

Implemented in tasks/schema.py order_tasks().

How to add to this map

When you add a new file or concept that other readers will hit:

  1. Decide which layer it belongs to (human / protocol / runtime / investigations).
  2. Add it to the relevant L1 diagram above (label + edges to siblings).
  3. If it's complex enough to need its own L2 detail, add a sub-section.
  4. If it's simple enough that it fits in prose, don't add a diagram. Re-read MERMAID-CONVENTIONS.

The map is allowed to lag the code by ≤ a session. Beyond that, it counts as drift and goes in tasks/TODO.md as a bad-rated task.