Story: Compass quality of life
Table of Contents
This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Continued from: Compass quality-of-life improvements.
Goal
Deliver a second round of small, independent compass improvements that do not warrant individual stories, continuing the sprint 19 QoL grab-bag. Environment and integration fixes: source SSH_AUTH_SOCK from .env so sandboxed sessions can push and fetch, fix the Emacs dashboard's compass invocation, and auto-authorise compass commands in Claude Code settings. Workflow ergonomics: actionable search results, newest-first journal log with –limit, a –commit option for captures, story search by exact folder name, and a task move command.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | None. |
| Last touched | 2026-06-10 |
Acceptance
- compass.sh exports SSH_AUTH_SOCK from .env alongside the other ORES_ variables; git push/fetch work from sandboxed sessions.
- Services start cleanly from the Emacs dashboard; the quoting/argv bug in the elisp compass runner is fixed.
- Claude Code settings auto-authorise compass commands; permission prompts for compass invocations are gone.
- compass search output is actionable (compass show hints, type, answer extracts) and finds stories by exact folder name.
- compass journal log prints newest-first with –limit; –chronological restores the old order.
- compass add capture –commit lands a capture and its index in a single conventional commit.
- compass task move relocates a task between stories, rewiring both Tasks tables and parent links, UUID intact.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Load SSH_AUTH_SOCK from .env in compass.sh | DONE | 2026-06-06 | 2026-06-06 | compass.sh does not export SSH_AUTH_SOCK, so git push/fetch from sandboxed sessions need manual agent setup; source it from .env alongside the other ORES_ vars. Re-filed from the closed CLI UX redesign story (task CCFF58E1). |
| Dashboard cannot start services via compass: whole command treated as one path | DONE | 2026-06-06 | 2026-06-06 | Starting services from the Emacs dashboard fails with: /bin/bash: /home/marco/Development/OreStudio/OreStudio.local1/projects/ores.compass/compass.sh services start: No such file or directory [exited abnormally with code 127]. The error shows the entire command string ('compass.sh services start') being treated as a single executable path — likely a quoting/argv bug in ores-dashboard.el / ores-db.el's compass invocation (string passed where an argv list or shell -c form is needed). Fix the elisp runner and check the other compass calls from the dashboard for the same pattern. |
| Review Claude Code settings: auto-authorise compass commands | DONE | 2026-06-06 | 2026-06-06 | Register the key compass commands in Claude Code settings (CLAUDE.md or settings.json) so they are available as shell shortcuts without needing to type the full path each time. |
| Make compass search results actionable | DONE | 2026-06-06 | 2026-06-06 | Observed: Claude bypasses compass search because the result format does not look directly useful — a title, tags, a path, and an ellipsised snippet, with no obvious next action. Refactor the output to be focused and actionable: one tight block per hit with a ready-to-run yellow hint (compass show <UUID>, matching the house hint UX used by audit/fleet), the doc type, and ideally a direct answer extract for question-shaped queries (recipes' Question/Answer sections). Fewer, better-ranked results beat ten loose ones; consider –limit defaulting low and a -v for the current verbose form. |
| Add a –commit option to compass add capture | DONE | 2026-06-06 | 2026-06-06 | compass add capture should grow an option (e.g. –commit) that, after creating the capture file and regenerating the inbox index, commits just those files with a standard message derived from the capture itself (e.g. '[agile] Capture: <title>' with the description as body and the house Co-Authored-By trailer). Captures filed mid-task currently interrupt the flow: each one needs a hand-written commit or risks getting tangled into unrelated staged work. |
| Add support to compass to search stories by folder name | DONE | 2026-06-06 | 2026-06-06 | Improve compass search to support a common use case which is to search by exact folder name, with underscores. |
| Add compass task move: relocate a task between stories | DONE | 2026-06-06 | 2026-06-06 | Add a compass command to move a task between stories. Today there is no 'task move': relocating a task means reverting the old story's wiring, re-running compass add with –id into the new parent, deleting the old file, and hand-editing tables. A 'compass task move <slug> –story <target>' should rehome the file, rewire both Tasks tables, and update the task's parent links. |
| compass journal log: newest-first with –limit | DONE | 2026-06-06 | 2026-06-06 | journal log prints oldest-first so fresh entries drown at the bottom (and head-clipping shows stale entries). Default to newest-first like git log, add –limit N / -n N to clip, and –chronological to restore oldest-first. |
| Boost search ranking by inbound-link count | DONE | 2026-06-06 | 2026-06-06 | Apply a link-count boost to compass search: docs linked by more nodes surface higher, stories linked by their tasks float above peripherally-tagged docs. |
| Boost recipe results for 'how do' queries | DONE | 2026-06-06 | 2026-06-06 | When a search query starts with 'how do', rank recipe docs first regardless of FTS score — recipes are titled as the question they answer and are almost always the right result. |
| Add scoped search to compass | DONE | 2026-06-10 | 2026-06-10 | compass search cannot be restricted to a repo path or doc type; backlog-only full-text search currently requires raw grep. |
| compass capture promote copies the capture's What section in… | DONE | 2026-06-10 | 2026-06-10 | compass capture promote copies the capture's What section into the task Goal verbatim, including the '(One paragraph: the idea.)' template placeholder when the capture body was never filled in, and appends an all-placeholder 'Promoted from capture' section. Promote should detect placeholder What/Why/References/See-also content (the literal template strings), fall back to the capture description for the goal, and omit empty placeholder subsections from the promoted body. |
| Gate the PR review round on unaddressed comments | DONE | 2026-06-07 | 2026-06-07 | pr-address-review and its runbook synced/rebased before checking whether a round existed, churning CI and force-pushing for nothing. |
| Add compass story tasks: list tasks under a story directly | DONE | 2026-06-10 | 2026-06-10 | compass story <id> (or –tasks flag) should enumerate all tasks in a story with their state, branch, and PR — without requiring the caller to navigate outgoing links from compass show. |
| Wire cross-reference tables in story new / task new | DONE | 2026-06-10 | 2026-06-10 | compass story new and task new scaffold the story/task docs but leave their cross-references unwired and their Goal/Acceptance as placeholders. Observed: the new task is not added to the story's * Tasks table; story new does not add the new story to the sprint's * Stories table (the tool prints both as manual 'next steps'); and neither accepts –goal/–acceptance, so docs are born without content. Make scaffolding wire the story<->task and sprint<->story table rows automatically, and accept –goal/–acceptance (matching the documented expectation that scaffolding wires the tables and is born with content). |
| Add –pr option to compass capture to branch, commit, and open PR | DONE | 2026-06-10 | 2026-06-10 | compass capture –commit commits the capture on the current branch but cannot push or create a PR because there is no task doc and branch protection blocks direct main commits. Add –pr that creates a capture/<slug> branch off origin/main, commits the capture and regenerated indexes, pushes the branch, and opens a PR via gh pr create — no task doc required. |
| compass capture –pr fails cleanly when capture file already exists | BACKLOG | When the capture file already exists in the working tree (e.g. hand-filled before –pr is called), codegen refuses to overwrite it and _capture_pr_flow aborts — but the capture/<slug> branch has already been created, leaving a dangling empty branch. Detect the pre-existing file before branching, or skip codegen and use the existing file. |