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 (or status) 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 the agile product owner skill already uses.
  • It lists every story and task under the current sprint whose State is STARTED, with file path and :ID:.
  • The query runs without an Emacs round-trip — it reads doc/agile/versions/ directly, so it does not depend on org-roam-db-sync or .compass.db.
  • Output is available in pretty (human) and json (tooling), matching the existing search formats.
  • The relationship to ores.codegen is resolved: compass reuses its doc_index parser 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 the list / show commands) for discovery and adds the one field it lacks — the State value in each doc's * Status table. Rejected: routing through the list command (it does not expose State) and the FTS cache (.compass.db can be stale; the agile tree is always current).
  • "Current" = highest folder sequence number for both version and sprint, matching the agile product owner skill's rule. A numeric key (_seq_key) is used so v10 > 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.

Emacs 29.1 (Org mode 9.6.6)