Story: ores.compass Locate — temporal orientation
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
A contributor (human or LLM) can ask ores.compass "where are we?" and
get an immediate, accurate answer computed from the documentation graph:
the current version, the current sprint, and the stories / tasks
currently in flight. This is the Locate pillar of the ores.compass
component — it replaces the manual "grep the agile tree to find the
highest sprint folder and its STARTED items" ritual with one command.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Complete — where / status shipped (PR #813). |
| Waiting on | Nothing. |
| Next | Done. |
| Last touched | 2026-05-24 |
Acceptance
compass.sh where(orstatus) prints the current version and current sprint — title and:ID:for each — where "current" is the version/sprint folder with the highest sequence number, matching the rule theagile product ownerskill already uses.- It lists every story and task under the current sprint whose
StateisSTARTED, with file path and:ID:. - The query runs without an Emacs round-trip — it reads
doc/agile/versions/directly, so it does not depend onorg-roam-db-syncor.compass.db. - Output is available in
pretty(human) andjson(tooling), matching the existingsearchformats. - The relationship to ores.codegen is resolved: compass reuses its
doc_indexparser rather than duplicating the listing logic.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Task: Implement the where command | DONE | 2026-05-24 | 2026-05-24 | Add a where/status subcommand reporting the current version, sprint, and in-flight stories and tasks. |
Decisions
- Source of truth (resolved). Locate reads the agile tree directly.
It reuses the bundled
doc_index(the canonical org parser, shared with thelist/showcommands) for discovery and adds the one field it lacks — theStatevalue in each doc's* Statustable. Rejected: routing through thelistcommand (it does not exposeState) and the FTS cache (.compass.dbcan be stale; the agile tree is always current). - "Current" = highest folder sequence number for both version and
sprint, matching the
agile product ownerskill's rule. A numeric key (_seq_key) is used sov10>v9(not a lexicographic compare).
Out of scope
- Mutating state (advancing TODOs) — Locate is read-only.
- Predicting or recommending the "next" piece of work.
- Cross-version timelines or burndown/velocity reporting.