Task: Implement the where command

Goal
Status
Acceptance
Plan
Notes
Result
PRs
Review

This page documents a task in the ores.compass Locate — temporal orientation story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Add a where subcommand (alias status) to ores.compass that prints the current version, the current sprint, and the stories and tasks currently in flight, in both pretty and json form — so a contributor or LLM can orient in one command.

Status

Field	Value
State	DONE
Parent story	ores.compass Locate — temporal orientation
Now	Implemented and smoke-tested.
Waiting on	Nothing.
Next	Review.
Last touched	2026-05-24

Acceptance

compass.sh where prints the current version and sprint (title + uppercase :ID: + path).
It lists in-flight (State STARTED) stories and tasks under the current sprint, with id and path.
-f json emits a structured version / sprint / in_flight document; status works as an alias.
Runs with no org-roam.db present (Locate does not need it).

Plan

Decide the source of truth (done — see the story's * Decisions: reuse doc_index, read State from the * Status table).
Add load_doc_index (sys.path import of codegen's parser), read_state, and cmd_where; wire the where=/=status subparser and skip the org-roam.db check for it.
Polish output: uppercase canonical IDs; strip the Story:=/=Task: title prefix next to the type column.
Smoke-test both formats; confirm search still works.

Notes

"Current" is the version/sprint folder with the highest sequence number. In-flight uses State = STARTED= parsed from each doc's * Status table via STATE_RE.

Result

Implemented in projects/ores.compass/src/compass.py (cmd_where plus load_doc_index / read_state helpers and the where / status subparser). Verified: where reports Version 0 / Sprint 18 and eight in-flight items; -f json emits the structured document; search unaffected; py_compile clean. Reuses ores.codegen's doc_index, so no frontmatter parsing is duplicated.

PRs

PR	Title
#813	[ores.compass] Locate pillar + fold doc-navigation out of codegen

Review

From the PR #813 gemini-code-assist review (squash-merged as de74b85e3). The reviewed code spans this task (cmd_where / read_state) and the consolidation task (the list / show imports).

#	Comment summary	Severity	Decision	What I did
1	Imports done inside sub-commands violate PEP 8	high	Fixed	Hoisted `doc_index` / `doc_list` / `doc_show` to module top (after the `sys.path` setup); removed the `load_doc_index` helper.
2	`read_state` reads whole file; catch decode errs	medium	Fixed (partial)	Added `UnicodeDecodeError` to the `except`. Kept the full read — the `State` row can follow a long `* Goal`, so a fixed chunk risks dropping in-flight items.
3	`d.id` could be `None` → `AttributeError`	medium	Declined	`doc_index` skips files without an `:ID:`, so `d.id` is always present for loaded docs; a guard would be dead code.

All three review threads were replied to and resolved before merge.