Story: ores.compass repository compass tool
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
ores.compass exists as a proper Python project under projects/ — a
repository "compass" that orients a contributor (human or LLM) in three
ways: Locate (where we are in time — version, sprint, in-flight
stories and tasks), Search (semantic retrieval of relevant docs from
cached org-roam data), and Scaffold (add stories, tasks, sprints,
recipes via codegen). The capability already prototyped as a loose
script (search) becomes the first pillar of a documented, structured
application. See the component overview for the full design.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Complete — all four pillars shipped (PRs #808, #813, #815). |
| Waiting on | Nothing. |
| Next | Done. |
| Last touched | 2026-05-24 |
Acceptance
projects/ores.compassexists as a regular Python project (venv bootstrap,src/,requirements.txt,modeling/) and the existing search code lives there rather than inscripts/.modeling/component_overview.orgdocuments the purpose, the three pillars, the project structure, and the open design questions, and passesvalidate_docs.sh.- The Search pillar still works from its new home
(
projects/ores.compass/compass.sh search "<query>"). - Locate and Scaffold are specified (not necessarily implemented) with their relationship to ores.codegen resolved.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Task: Define scope and structure for ores.compass | DONE | 2026-05-24 | 2026-05-24 | Brainstorm and document the purpose, capabilities, and project structure of ores.compass before implementation. |
| Task: Consolidate doc-navigation into compass and add usage recipes | DONE | 2026-05-24 | 2026-05-24 | Move doc_index/doc_list/doc_show from ores.codegen into ores.compass as compass list/show; delete codegen copies; repoint references; add compass recipes. |
| Story: ores.compass Locate — temporal orientation | ||||
| Story: ores.compass Scaffold — agile authoring over codegen |
Decisions
- The Sprint 18 capture asked for "a tool called compass". The existing
scripts/compass.pyFTS prototype is adopted as the Search pillar and relocated into the new project rather than rewritten. - Compass wraps ores.codegen for scaffolding instead of duplicating
generate_v2_doc.sh. (Doc navigation later moved the other way: thedoc_list/doc_show/doc_indexscripts were folded into compass — see the consolidation task.)
Out of scope
- Embedding / vector search beyond SQLite FTS5.
- Emacs integration, dashboards, and the capture-drain skill (separate captures).
- Live file watching; compass reflects the last
org-roam-db-sync+indexrun.