Oak: A Version Control System Reimagined for AI Agents 🌳

Oak is a specialized alternative to Git, engineered specifically to serve as the foundational substrate for autonomous agents. It moves beyond traditional versioning to provide a "space" where agents can operate efficiently across multiple repositories.

🛠️ Core Command Suite

The Oak CLI provides a streamlined interface for both humans and agents to interact with codebases.

---

🔄 The Agentic Workflow

Unlike human developers, agents require strict contracts to ensure they don't corrupt the main codebase or leave "ghost" changes.

📋 Agent Finishing Checklist

To maintain repository integrity, agents must adhere to the following:

• No Mutation of canonical checkouts.
• No Local-Only checkpoints (must be visible to reviewers).
• Commit all changes.
• Describe the work performed.
• Push to a reviewable branch.

---

📈 Recent Evolution & Changelog

Oak has undergone rapid iteration, moving through versions v0.98.0 and v0.99.0. The development focus has shifted toward agent-native launch contracts and system hardening.

🛡️ Security & Validation

The system now aggressively rejects malformed data to prevent injection or filesystem errors:

• Identity Protection: All control characters are now rejected in org/repo specs, commit identity fields, and oak site organization slugs.
• Filesystem Integrity:
  • .oak markers must be directories.
  • Tree entry filenames cannot contain control characters.
  • SQLite database permissions are hardened to $\text{mode} = 0600$.
• API Safety: Organization slugs are validated before being used as API identifiers.

🤖 Agent-Specific Logic

The "Launch Contract" ensures agents behave predictably:

• The Finish Saga: The finish process is now a retryable sequence (rather than rollback-atomic) that preflights authentication and remote reachability before any local mutation occurs.
• State Management: recommended_action.kind is now a closed enum to prevent agent hallucination.
• Scale Gates: Implementation of $n10/n100$ scale gates for branch review and triage.
• Isolated Workers: Explicit rules now forbid agents from mutating canonical checkouts.

⚡ Performance & Compatibility

• Windows Support: The Oak CLI now builds and runs natively on Windows.
• Lazy Loading: Large-repo mount startup is now root-only and lazy over committed trees.
• Git Integration:
  • Accelerated git import speeds.
  • CI fallback identities allow reflog writes even without user.name or user.email configured.
  • oak merge can now handle main-parent branches without requiring a checkout hop.

🎨 UI & UX

• Visual Identity: The macOS app icon has been updated to a pixel-art compass mark.
• Design Language: Browser login pages now follow the oak.space black-and-white aesthetic.
• Accessibility: Added a high-contrast app icon.

---

⚙️ Technical Implementation Details

Release Proofing

The team has refined how releases are verified. Manual proof via oakvcs-cli cargo publish --dry-run $\rightarrow$ New non-mutating release-proof target.

This new workflow:

1. Encodes the correct core dry-run.
2. Uses a CLI build proxy.
3. Verifies version lockstep.
4. Ensures release signing is explicit and "fail-closed."

Code Quality

The project maintains strict adherence to Rust standards:

// Example of the internal focus on formatting and imports
// Reordered imports in merge.rs and review.rs to satisfy rustfmt
use oak_core::vcs::merge;
use oak_core::vcs::review;

• Toolchain: Pinned to 1.94 for cargo fmt --all --check.
• Pathing: Fixed repo-relative path resolution for .. paths to preserve symlink boundaries.

Summary of Recent Merges