reliquary/plugins/orbit/README.md

orbit (prototype)

This plugin is a skill for structural review of Rust changes with the GitLab orbit code graph. It reports changed definitions, blast radius, trait-impl coverage, crate and module boundary guards, and a cfg-blindness preflight that decides how far to trust the rest. It complements grep and does not replace it.

It is an early prototype built from the 2026-09-29 research in docs/workpad/research/2026-09-29-17-orbit/, for orbit CLI 0.133. It expects orbit, git and python3 on PATH. No compilation is involved.

Contents

Path	What
skills/orbit/SKILL.md	When to use orbit rather than grep, the mandatory preflight, the review pass, reporting rules, feedback, and how to brief a subagent
skills/orbit/references/review-recipes.md	Per-recipe detail, the gap-class table with grep fallbacks, and the rules-file format
skills/orbit/references/cookbook.md	Ad-hoc CLI and SQL for Rust, and gotchas
skills/orbit/scripts/review-pass.sh	End-to-end pass: setup, then preflight, defdiff, blast, traits, boundary and context (about 25 s)
skills/orbit/scripts/review-setup.sh, review-teardown.sh	Detached worktrees for base and tip in an isolated --db, and their cleanup
skills/orbit/scripts/*.py	The recipes (ob.py and regions.py are libraries)
skills/orbit/scripts/freshness.sh	Read-only index freshness check for ad-hoc questions
skills/orbit/scripts/fb.sh	Appends one feedback record
skills/orbit/scripts/rules/*.rules	Boundary rules for spacecraft and dirigent (hand-derived, may drift)
skills/orbit/scripts/sql/*.sql	Standalone SQL templates

Review scratch (worktrees, DBs, outputs) goes to $ORBIT_REVIEW_HOME (default ~/.cache/orbit-review), never /tmp. Always run review-teardown.sh afterwards: orbit has no command to delete an index entry, so nothing review-related may go into the shared ~/.gitlab/orbit/graph.duckdb.

Enabling locally (spacecraft, dirigent)

Both projects already declare the reliquary marketplace in their committed .claude/settings.json (extraKnownMarketplaces). That marketplace is fetched from git (git@git.g4b.org:dirigence/reliquary.git), so orbit@reliquary only resolves after this plugin is committed and pushed, and the marketplace has refreshed (/plugin marketplace update reliquary).

Per project, not committed. Run this in the project root:

claude plugin install orbit@reliquary --scope local

--scope local writes to .claude/settings.local.json, which is meant to stay uncommitted (confirm with git check-ignore .claude/settings.local.json). To do it by hand, add this to <project>/.claude/settings.local.json (create it if missing, and merge with any existing keys):

{
  "enabledPlugins": {
    "orbit@reliquary": true
  }
}

Before pushing (trying out this working copy), load the plugin for one session only:

cd ~/Projects/spacecraft   # or ~/Projects/dirigent
claude --plugin-dir ~/Projects/reliquary/plugins/orbit

Check it with /plugin (orbit should be listed as enabled) or by asking "review this branch with orbit". Also useful:

• claude plugin validate ~/Projects/reliquary/plugins/orbit
• Rules files: rules/spacecraft.rules and rules/dirigent.rules ship with the plugin. Pass one as the 5th argument to review-pass.sh.

Feedback log

While this is a prototype, the skill asks agents to append one JSONL line per orbit result that informed a decision (or should have, and turned out wrong):

ORBIT_AGENT=search skills/orbit/scripts/fb.sh blast grep-needed "callers of format_token_title" "blast.py dg-tokens" 0 "both call sites inside rsx!" rsx

• File: ~/.local/share/orbit-skill/feedback.jsonl. Set ORBIT_FEEDBACK to override it. It is outside every repo and shared across projects.
• Fields: ts, repo, commit, dirty, orbit (automatic), agent ($ORBIT_AGENT), recipe, purpose, cmd, rows, verdict, and optionally note, gap. verdict is one of useful | wrong | incomplete | grep-needed | noise | unused.

To read or mine it:

F=~/.local/share/orbit-skill/feedback.jsonl
jq -s 'group_by(.recipe, .verdict) | map({recipe: .[0].recipe, verdict: .[0].verdict, n: length})' $F   # value per recipe
jq -s '[.[] | select(.gap != "")] | group_by(.gap) | map({gap: .[0].gap, n: length}) | sort_by(-.n)' $F  # which blind spots bite
jq -c 'select(.verdict == "wrong" or .verdict == "incomplete") | {repo, recipe, purpose, note}' $F        # failures to learn from
jq -s 'group_by(.repo) | map({repo: .[0].repo, n: length, dirty: map(select(.dirty)) | length})' $F      # per project, dirty-tree usage

Summaries of mined data (not raw logs) belong in docs/workpad/research/…. The open questions the log is meant to answer (whether the pass changes outcomes, the preflight thresholds, token budget, agent fit) are listed in §11 of phase-2-review-workflows.md.

Known rough edges

• Tested only on orbit 0.133.0, spacecraft and dirigent. The preflight thresholds (25 % and 60 %) are guesses.
• Uncommitted review uses git stash create, so untracked files are not reviewed.
• review-setup.sh briefly registers two worktrees in the target repo's .git (removed by teardown). If teardown is skipped, they linger. Check with git worktree list.
• Rust only. The shell scripts need bash (they work when called from fish).