reliquary/docs/workpad/journals/2026-09-29-17-orbit.md

# Orbit research and skill — Igor Session Journal

**Date**: 2026-09-29
**Topic**: orbit (code-graph CLI): research tree, toward a skill
**Worktree/branch**: main (markdown only)

## Log

<!-- Append-only. This journal is the testimony of one path through the problem: record the tangents and dead ends, not only the results. The path can't be walked again; the record can be read. -->

- 17:00 — The user provided `local/orbit_guide.md`, a field guide on orbit from a Python/Django project, and wants a small research tree plus, eventually, a skill.
- 17:00 — `orbit` 0.133.0 is installed at `~/.local/bin/orbit`; the guide assessed 0.124.0.
- 17:00 — Recorded the guide as `research/2026-09-29-17-orbit/phase-0-field-guide-python-django.md` (with a provenance header; the user's intro note dropped). Wrote `goals/orbit-skill.md` and a draft tree plan `research/2026-09-29-17-orbit/plan.md`. Waiting for the user to confirm the plan, the test-bed repositories and where the skill should live.
- 17:05 — Direction from the user: the Python guide is baseline guidance for an early prototype skill. The target is Rust Spire projects, with review as the first use case. Plan revised.
- 17:08 — Dispatched the phase-1 rust-capabilities probe on dirigent (Opus). The user stopped it: I had misread the direction. Correction: the only off-limits repo is the Python one the guide came from. Test beds are spacecraft and dirigent, and any `~/Projects` repo is allowed. Plan updated. Waiting for the go to relaunch.
- 17:12 — The user gave the go. Relaunched phase 1 in parallel: rust-capabilities (Opus; spacecraft and dirigent, read-only, scratch in ~/.cache/orbit-probe/) → `phase-1-rust-capabilities.md`; review-fit (Sonnet; Spire review stage, skill placement) → `phase-1-review-fit.md`.
- 17:15 — review-fit came back → `phase-1-review-fit.md`. There is no pinned reviewer agent (stage 6 is an ad-hoc Opus reviewer). `search` is the best fit to run orbit. Recommended placement: a standalone `plugins/orbit/`, following the tome precedent. `project.md` can flag orbit availability through its existing domain-skills slot. Waiting for rust-capabilities.
- 17:17 — The user notes that orbit had already indexed the projects beforehand. Told rust-capabilities that the existing `orbit list` entries are the user's and must not be removed, and asked it to compare each indexed commit with HEAD (a staleness check).
- 17:48 — rust-capabilities came back → `phase-1-rust-capabilities.md`.
  - **CALLS:** 85–100% coverage for concrete calls; 0–14% for `dyn Trait` calls.
  - **Missed code:** calls inside macro arguments, bevy systems registered via `add_systems`, and Dioxus components used in `rsx!`.
  - **Blind spots:** all Cargo features treated as off (defaults too) and `#[cfg(test)]` skipped; 176 of 989 dirigent files have no definitions, including the whole server backend.
  - **Timeouts:** under default threads some large files time out and are skipped nondeterministically; use `-t 4` and check `skipped_files`.
  - **Traits:** impls are only linked when in the same file as the type.
  - **MCP:** still three tools, and `run_sql` is unscoped.
  - **Staleness:** a stale commit gives little or no warning.
  - **Branch comparison works:** a detached worktree plus one SQL query. `--db` gives an isolated DB, and orbit has no delete command.
  - **Leftover:** a spacecraft worktree entry `bfbbcd96` remains in the shared DB `~/.gitlab/orbit/graph.duckdb`.
  - **Re-indexed:** spacecraft and dirigent, which were stale. Orbit writes nothing into repos. Scripts are in `~/.cache/orbit-probe/`.
- 17:55 — User direction: the research must not compile anything. Worktrees are fine. The skill should record feedback data and be enabled locally on spacecraft and dirigent, with findings mined later. Accreted this to the plan and the goal. Dispatching phase 2 review-workflows (Opus). The leftover DB entry is still waiting on the user.
- 17:58 — User decision: remove leftovers at the end of the session. That covers the `bfbbcd96` entry in the shared DB, `~/.cache/orbit-probe/` (worktrees, isolated DBs, scratch), and `local/orbit_guide.md` once the user has confirmed.
- 18:00 — User decision: keep `local/orbit_guide.md` as an artifact for now. It is not part of the cleanup.
- 18:10 — The user flagged scope creep ("a forever task"). Narrowed phase 2 mid-run: one repo, recipes 1, 2 and 5 tested, the rest as untested drafts, feedback format included. Phase 3 synthesis dropped: next step is drafting the prototype skill directly.
- 19:35 — Phase 2 came back after about 96 minutes → `phase-2-review-workflows.md`. The scope cut arrived too late: the report covers both repos, 7 ranges and all 6 recipes. Lesson: send a scope cut early or not at all; this brief was oversized for a prototype.
  - **Changed definitions:** exact in the code orbit can see.
  - **Preflight:** 6–71% of changed lines are invisible to orbit, so the preflight is mandatory.
  - **Blast radius:** 49% of dependents per definition, 93% per file.
  - **Feedback log:** JSONL at `~/.local/share/orbit-skill/feedback.jsonl`. Scripts are in `~/.cache/orbit-probe/recipes/`. Worktrees and isolated DBs are cleaned up; the shared DB is unchanged, so `bfbbcd96` is still there.
  - **Corrects phase 1:** orbit indexes the working tree, including uncommitted and untracked files, but labels the index with HEAD's commit.
- 19:36 — Dispatched the prototype plugin build (Opus): `plugins/orbit/`, with the recipes carried into the plugin. No design or plan stage: this is a prototype, and the user asked for speed.
- 19:45 — Prototype plugin built in about 8.5 minutes → `plugins/orbit/` (skill, references, scripts, `fb.sh` feedback helper, `freshness.sh`), and registered in `marketplace.json`. It is uncommitted.
  - **Tested:** the review pass ran end to end on dirigent `cd4e8f70` in a scratch clone and isolated DB (23 s, 8 KB of output, results match phase 2). `claude plugin validate` passes. The shared DB is unchanged.
  - **Enabling:** `claude plugin install orbit@reliquary --scope local` (after a push), or `--plugin-dir` before that.
  - **Rough edges:** untracked files are not reviewed, the preflight thresholds are guesses, `${CLAUDE_PLUGIN_ROOT}` expansion in SKILL.md is unverified, and the boundary rules may drift.
- 19:50 — The user said commit, push and wrap up.
  - **Leftover DB entry:** removed `bfbbcd96` from the shared orbit DB. Orbit has no delete command, so I backed up the DB, then deleted that project's rows from the four gl_* tables, its edges (0 ID collisions with other projects), its gl_def_doc table, its FTS schema and its manifest row. I checked the copy with `orbit list`, `sql` and `grep` and swapped it in only after confirming by sha256 that the original was unchanged.
  - **Concurrent re-index:** another session re-indexed spacecraft (`82c45927`) right after the swap. The DB stays consistent: 3 entries, and spacecraft matches HEAD.
  - **Scratch:** deleted `~/.cache/orbit-probe/` and the backup. No probe worktrees remain in either repo.
  - Kept `local/orbit_guide.md` (uncommitted, as before).
- 19:52 — Wrap-up. There are no adepts to close. Committing the research, goal, journal and `plugins/orbit/`, then pushing. The user's other uncommitted changes are left alone.

## Adepts

- Roster empty at boot. An `orbit` adept may earn its place if consultation recurs.
- None spawned this session.

## Artifacts

- `research/2026-09-29-17-orbit/phase-0-field-guide-python-django.md`
- `research/2026-09-29-17-orbit/plan.md`
- `goals/orbit-skill.md`
- `research/2026-09-29-17-orbit/phase-1-review-fit.md`
- `research/2026-09-29-17-orbit/phase-1-rust-capabilities.md`
- `research/2026-09-29-17-orbit/phase-2-review-workflows.md`
- `plugins/orbit/` (prototype plugin, uncommitted)

## Open threads

- Enable the plugin locally on spacecraft and dirigent (`claude plugin install orbit@reliquary --scope local`, now that the plugin is pushed).
- Mine `~/.local/share/orbit-skill/feedback.jsonl` after some real reviews. The phase-2 report lists the 11 questions it should answer.
- Rough edges in the prototype: untracked files are not reviewed, the preflight thresholds are guesses, `${CLAUDE_PLUGIN_ROOT}` expansion in SKILL.md is unverified, the boundary rules are hand-derived, and worktrees linger if teardown is skipped.
- Optional later: wire orbit into Spire (a `project.md` flag through the domain-skills slot, and briefs for the search agent). A dedicated reviewer agent for stage 6 does not exist yet.
- `goals/orbit-skill.md` still lists "Open" items that are now answered (standalone plugin; spacecraft and dirigent). Leave them for the curator or the user to settle.

## Graduation candidates

- **Orbit's blind regions in Rust** (cfg(test), all Cargo features treated as off, macro, `dyn`, `add_systems` and `rsx!` gaps; impls linked only when in the same file as the type). Anyone using orbit on Rust would otherwise re-derive this at great cost. It already lives in the skill; the research reports hold the evidence.
- **Orbit labels a working-tree index with HEAD's commit.** This is non-obvious, it corrected phase 1, and it affects every "is my index fresh" judgement.
- **Removing an entry from orbit's DuckDB by hand** (manifest row, gl_* rows by `project_id`, edges by ID, `gl_def_doc_<pid>` table, FTS schema). Orbit has no delete command, and this took a schema dig to work out.

## Self-review

- Over-scoped. The phase-2 brief (6 recipes × 2 repos × 7 ranges) was sized for a finished skill, not a prototype, and ran about 96 minutes. The user had to flag it as a "forever task". The cut came too late to matter: scope has to be sized at dispatch, not trimmed mid-run.
- Misread the user's direction twice at the start: first "no Python repo" as "no Python at all", then the test-bed question. I relaunched an agent that could have been redirected if I had asked one sharper question first.
- Delegation worked where it mattered: the research and the plugin build went to agents that wrote their own files. The prototype build, briefed tightly with a timebox, took about 8 minutes.
- I did the DB cleanup, the commit and the journal myself rather than delegating. That was defensible for a careful, stateful operation on the user's shared DB, but strictly off-mindset.
- The race on the shared DB (another session indexing during the swap) was caught only by checking after the swap. Future DB surgery should take a lock or ask other sessions to pause.