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

• 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.