Skip to content
Orbit Orbit Orbit

Worktree Artifacts - Vision

Mirrored from docs/design/worktree-artifacts/3_vision.md. Edit the source document in the repository, not this generated page.

The worktree artifact model should make knowledge artifacts feel like ordinary branch files without weakening Orbit’s shared coordination state.

1. Open Questions

Section titled “1. Open Questions”
  1. Should remote stubs grow an optional cached envelope so include_remote can show titles and summaries without reading body files?
  2. Should Orbit offer a repair command for stale body_path rows after users move or delete linked worktrees manually?
  3. Should ADR and learning updates refuse to mutate bodies outside the current worktree, or offer an explicit remote-edit mode?
  4. Should sync/hosted modes replace local filesystem body paths with content-addressed blobs?

2. Prior Work

Section titled “2. Prior Work”

Runtime Roots

Section titled “Runtime Roots”

[ORB-00199] established the root split that this design depends on. The important precedent is that existing shared state stays bound to shared_root unless a task deliberately flips it.

Allocation

Section titled “Allocation”

[ORB-00200] established SQLite as the ID authority and moved learning IDs to L-NNNN. That made per-worktree body storage possible without filesystem-scan collisions.

Artifact Discipline

Section titled “Artifact Discipline”

The ADR and learning skills already require tool-mediated writes instead of direct YAML edits. [ORB-00201] changes where those tool-mediated writes land, not the authorship rule.

3. What May Be Distinctive

Section titled “3. What May Be Distinctive”

The model separates artifact identity from artifact body locality. IDs and allocation rows are global enough for cross-worktree references; bodies stay branch-local enough for normal git staging and review.

The remote-stub behavior also gives agents a gentle failure mode: they can see that an artifact exists without pretending to know its unreadable content.

4. References

Section titled “4. References”

Task References

Section titled “Task References”
  • [ORB-00199] introduced shared/local root resolution.
  • [ORB-00200] introduced shared ID allocation and L-NNNN.
  • [ORB-00201] implemented local artifact bodies and federation.

Resolve any task above with orbit task show <ID> or git log --grep=<ID>.