# Oxygen roadmap

One ordered plan across the products: **oxygen** (`oxy`, the VCS),

**oxygen-vscode** (the editor extension), **oxygenhub** (the forge),

**oxygenhub-vscode** (the forge in the editor) and the **runner** (CI).

Each product keeps its own `docs/plan.md` with the checklists; this file

is the order and the reasons. Started 2026-09-27.

Rules that apply throughout: a phase is done when its tests pass, clippy is

clean, the change is committed with `oxy` and pushed to the hub on Earth;

oxygen is never checked into Git; specs are written and reviewed before

code when the phase changes a security-relevant rule.

| Phase | Product | Delivers | Unblocks |

|---|---|---|---|

| A | oxygen | Challenge signing, push report, `Send` state snapshot for caching, paginated history window with a shared graph layout | B, everything that caches |

| B | oxygenhub 0.2 | Accounts, sessions with TOTP, organisations and teams, roles, visibility by viewer, scoped tokens, linked identities, audit log, settings, attributed pushes | C, D |

| C | review | Adversarial review of oxy §14.4 (seal adoption), §16.1 (unbound repositories), hub §5 and §7 | D |

| D | oxygen + oxygenhub 0.3 | `oxy seal --proposal`, `oxy proposal show|land`; proposals, projected state, atom-anchored comments, seal-backed approvals, requirements, landing, stacking | E, F |

| E | oxygenhub 0.4 | Issues, labels, milestones, cross references, inbox, email, watching, search over issues and proposals | F |

| F | oxygenhub 0.5 + oxygen-vscode | Complete JSON API, `hub-api` types with generated TypeScript, webhooks, checks with seals, SSE status; the extension's exported API and remote-provider hook | G, I |

| G | oxygenhub-vscode | Spec, then sign-in, proposals, review threads, approve and land, issues, checks in the editor | — |

| H | oxygen + oxygenhub 0.6 | Delegate-signed changes from an edit set; web edits, browser conflict resolution, releases with assets and archives, Git mirror, code search | — |

| I | runner | `docs/runner.md`, `oxyrun` running pipelines locally in containers, hub job-claim API, results as seals, required checks | — |

| J | all 1.0 | oxygen-vscode on three platforms and the Marketplace; hub passkeys, backup drill, load test, security review, packaged release; oxy spec open questions (§28) closed | — |

## Phase A: oxygen groundwork

1. `oxy identity sign-challenge <hex>` and `oxy_core::identity::{sign_challenge, verify_challenge}` with a domain-separated message, for linking keys and for HTTP signature authentication later. Done when a hub can verify a signed challenge against an exported identity.

2. `receive_push` returns, per accepted reference, old state, new state and the newly stored changes; `oxy-server` passes it to `after_push`. Done when the hub's push log shows heads and change counts.

3. A `Send` snapshot type (`state::Frozen` or similar) holding the materialised tree, files and per-change metadata without `Rc`, so a host can cache by heads across threads. Done when the hub caches states and the overview of `oxygen` renders in under 100 ms warm.

4. `Repo::log_window(heads, cursor, limit)` and `graph::layout` in `oxy-core`, used by the CLI's log and the hub's history page. Done when both draw the same lanes for the same history.

## Phase B: oxygenhub 0.2

Order inside the phase: schema and password auth first (accounts, sessions, CSRF, sign in and out, profile), then roles and visibility (organisations, teams, collaborator roles, viewer-aware lookup and protocol authorisation), then tokens (scoped, hashed, per-repository), then linked identities (challenge flow, attribution on every page), then TOTP and sessions management, then the audit log and settings pages, and finally the admin pages (registration mode, accounts, storage). Milestone done when a private repository is invisible to outsiders, a push is attributed to the key that signed it, and a token with `repo:read` alone cannot push.

## Phase C: review checkpoint

Andy commissions the adversarial review. The questions to put to the reviewer: can an attacker who controls the hub forge history, approvals or policy (the design says no); does seal adoption of anonymous changes open a laundering path; can an unbound repository be hijacked before its owner pushes; are the hub's role checks and the repository's policy ever allowed to disagree in the attacker's favour. Findings become plan items before phase D starts.

## Phases D to J

Each is specified in the product's own spec: hub §7 (D), §8 and §10 (E), §12 and §13.1 (F), the oxygenhub-vscode spec to be written at G, hub §6.9, §9, §14 (H), the runner spec (I), and the 1.0 rows of each milestone table (J). Their checklists are added to the plan files when the phase begins.

## Progress

- 2026-09-27: roadmap written; phase A done the same day (challenge signatures, push report, `Send` states with the hub's cache, shared lanes and `log_window`).

- 2026-09-27: phase B (hub 0.2, accounts and access) done and deployed; phase C, the review checkpoint, is Andy's to commission.

- 2026-09-27: phase D done ahead of the review at Andy's request (`oxy seal --proposal`, `oxy proposal show|land`, seal-only pushes; hub 0.3 proposals and review). Review findings will be folded into D's code as plan items.