ores.compass

ores.compass is a small Python command-line tool that orients a contributor (human or LLM) inside the ORE Studio repository. It answers three questions against the project's org-roam documentation graph: where are we in time?, which documents are relevant to X?, and how do I add a new agile artefact?. It is the executable counterpart to the documentation Compass — the doc map tells a reader where things are; the tool computes the answer on demand from cached data. The search slice is implemented today; temporal orientation and agile scaffolding are planned (see the story).

Pillars (the first three drawn from the Sprint 18 capture * Tools):

1. Locate — "where are we in time?" Report the current version, the current sprint, and the stories / tasks currently in flight (State STARTED). Implemented as where / status — see the Locate story.
2. Search — semantic document retrieval. Given a query, return the most relevant documents from a cached index of the graph. Today this is SQLite FTS5 over the text of every org node; future work may add embedding-based ranking. Implemented.
3. Scaffold — agile authoring. Add a story to a sprint, a task to a story, a sprint, a recipe, a capture, etc. Calls codegen as a library rather than re-implementing it. Implemented as add — see the Scaffold story.
4. Fleet — "what is every worktree doing?" List each git worktree with its branch, mapped story + task (via the task #+branch: field), and open PR + live state, so parallel checkouts/agents don't collide. Implemented as fleet — see the Fleet story.
5. Goto — "start a unit of work." Fetch main, create a feature branch, scaffold the task (and, for a new story, the story too) via Scaffold/codegen with the task's #+branch: set, and print the remaining manual steps — the "start a story" ritual in one command. Two modes: new story (story new --slug/--title/--description) or add a task to an existing story (task new --story <id-or-slug> --slug --title). Implemented as story new / task new (formerly goto) — see the Goto story.

• .org-roam.db (or org-roam.db) at the repository root — the EmacSQL database produced by M-x org-roam-db-sync. The single source of truth for node text, titles, tags, outline paths, and links.
• The agile document tree under doc/agile/versions/ — versions, sprints, stories, tasks and the State value in each doc's * Status table (consumed by Locate).
• A search query string (consumed by Search).

• .compass.db at the repository root — a local SQLite FTS5 cache (compass_fts + compass_meta) rebuilt incrementally by mtime. Git ignored.
• Search results in three formats: pretty (default, human), line (UUID "path" "match", scriptable), and json (for tooling such as the knowledge-graph site).
• Planned: a temporal-orientation report, and new v2 .org artefacts (via codegen) for the scaffold pillar.

• projects/ores.compass/compass.sh — bootstraps the virtualenv (and installs requirements.txt if present) and forwards to the Python CLI.
• projects/ores.compass/src/compass.py — the CLI. Subcommands: index [--rebuild], search <query> [-l N] [-f FMT], debug [-f FILE] (Search); where / status [=-f pretty|json=] (Locate); list [filters] and show <uuid> (Navigate); add <type> [flags] (Scaffold); fleet [-f pretty|json] (Fleet); and story new / task new (Goto) — new story (--slug/--title/--description) or existing story (--story <id-or-slug> --slug --title); --dry-run for both.

Compass's temporal commands sit on a 2×2 grid — subject (me ↔ everyone) × time (now ↔ past):

Two substrates feed the grid, and which one a command may read is a rule, not an accident:

• Live substrate — per-worktree .journal.org files, branch and PR state. Approximate but immediate; only ever visible to the checkout it lives in. Now-views (fleet, journal) read this.
• Consistent substrate — the agile documents on origin/main, their git history, and the GitHub PR record. Identical from any fresh checkout. Past-views (timeline, sprint charts) read this and nothing else, so the same window always reconstructs the same history.

Other temporal commands are projections: where=/=status and sprint audit are sprint-scoped now-views; sprint charts aggregates the consistent substrate. New temporal features should be placed on this grid — and assigned a substrate — rather than added beside it. See the temporal command coherence investigation for the full analysis.

Each command pillar groups the subcommands that share a purpose. The shell entry point for all commands is projects/ores.compass/compass.sh; run it from the repository root.

• Python 3 standard library for everything except Scaffold (sqlite3, argparse, json, pathlib, re, dataclasses, subprocess).
• pystache — for add and story new / task new (Scaffold), which import codegen's Mustache-based generator. Declared in requirements.txt; the other commands run without it.
• git (fleet uses git worktree list; story new / task new use git fetch + git switch -c) and gh (live PR state in fleet and where --prs). fleet degrades gracefully when gh is unavailable.
• org-roam (in Emacs) to populate .org-roam.db, used only by the Search pillar. Compass never writes to it; it opens it read-only. Locate, Navigate and Fleet read the working tree directly and need neither org-roam.db nor org-roam-db-sync.
• ores.codegen — the division of labour is: codegen generates, compass navigates. Doc navigation (doc_index / list / show) was folded out of codegen into compass. Doc generation stays in codegen; the Scaffold pillar (add) calls codegen as a library (doc_generate.main(...)) to make stories, tasks and sprints — not shell out to, nor re-implement, generate_doc.sh.

projects/ores.compass/
├── compass.sh                 # venv bootstrap + CLI entry wrapper
├── requirements.txt           # pystache (only `add` needs it)
├── src/
│   ├── __init__.py
│   ├── compass.py             # CLI dispatcher: index/search/debug/where/list/show/add/fleet/story/task
│   ├── doc_index.py           # canonical .org parser (walks the repo)
│   ├── doc_list.py            # `list` — filter the doc graph
│   └── doc_show.py            # `show` — one doc + inbound/outbound links
└── modeling/
    ├── component_overview.org # this document
    └── ores.compass.puml      # component diagram source

The doc-navigation modules (doc_index, doc_list, doc_show) were moved here from ores.codegen so a single tool owns repository orientation. As the Scaffold pillar lands, compass.py may split into per-pillar modules behind a thin dispatcher.

• Codegen boundary. Resolved. Doc navigation (doc_index / list / show) now lives in compass; codegen keeps only code/doc generation (generate_doc.sh, which Scaffold will call). No parsing is duplicated across the two.
• Cache freshness. Search reads .compass.db, which is only as fresh as the last index run / org-roam-db-sync; decide how to refresh (manual, pre-command auto-index, or a git hook). Locate is unaffected — it reads the agile tree directly, always fresh.
• Name overlap. The tool shares its name with the documentation Compass. Intentional (both orient the reader) but should be called out wherever both are referenced. Action: update doc/compass.org to distinguish the two senses — ores.compass, the executable tool in projects/, versus "compass" the general orienting concept (the doc map, and the cybernetic notion of a device that tells a system where it is and which way it is heading). The doc map should note the tool as its executable counterpart and link to the ores.compass story.

• Story: ores.compass repository compass tool — the sprint story.
• Compass — the documentation map this tool complements.
• ores.codegen — the codegen backend for scaffolding and listing.