Core concepts

Scope, connection, Template, blueprint state, under construction, built, and how drift is kept honest.

Altitude has a small, locked vocabulary. These are the words that mean something specific.

Scope

A scope is the single primitive: a typed, labelled unit of your codebase with a permanent UUID. Identity is decoupled from location — moving or renaming a scope’s folder never changes its id.

A scope is stored in one of two forms:

• a manifest — a folder with an altitude.yaml pointing at real files, or
• a record — a folder-less card (.altitude/scopes/<id>.yaml) that groups other scopes.

Any scope may contain other scopes (its members). Every scope lives in exactly one other scope — its home. A scope that nobody lists sits at the top level; the project itself is the implicit root.

Connection

A connection is a first-class, buildable link between two scopes. It is not just an arrow — it can be a real pile of code (an API client, an adapter), so it has its own status. A connection stays proposed until the agent writes its code and reports it built; its status is never inferred from its endpoints.

Template

A Template is a scope’s type — the definition that sets which surfaces a scope shows and its icon and colour. Templates come in two forms:

• a declarative template.yaml (the default — plain data, language-neutral), or
• a code handler.ts (the power-user escape hatch for dynamic logic; it wins when both exist).

Identity — an icon and a colour — is a property of the Template, so every scope of a type shares one mark. Pick once; all of them change.

Surface

A surface is one of a scope’s content faces, rendered as a clickable tab in the reader panel. Three surface types ship:

• iframe — embed any URL (a rendered README, syntax-highlighted source, a Storybook story).
• terminal — spawn a command and stream it to a browser terminal (a test runner, say).
• hybrid — a static artifact with a Run button that switches to a live terminal.

Status — the lifecycle

Every scope and connection has a status:

• proposed — a spec whose code need not exist yet. This is blueprint state: a sketch meaning “build this.” Drawn in green (the diff “+”).
• under construction — the agent is durably building this. A committed state that survives a cancel or crash, so a fresh agent can always pick the work back up.
• built — real code exists and its fingerprint is clean. The default when status is absent.
• stale — a built item whose code has drifted out from under it. Badged amber.
• marked for removal — you deleted a built item on the board, instructing the agent to remove its real code. It stays on the map, struck through in red, until the agent deletes the code and completes the removal.

The diff language

The board speaks git-diff, one colour grammar everywhere: green = will exist (proposed), red = will stop existing (marked for removal), amber = drifted. Movement — the shimmer on an item the agent is building right now — is animated in that item’s own colour, never a colour of its own.

Drift and recovery

A built record starts lying when the code underneath it changes — a refactor edits a source, or the agent forgets to report a flip. Altitude does not prevent this; it makes it detectable.

At the moment a scope or connection flips to built, it stamps a fingerprint — the SHA-256 of the files it is built from. Re-hashing at the gate flags any built item whose bytes no longer match as stale — a hard error, so a stale “done” can’t stand. The agent resolves it by re-affirming (re-flip → re-stamp clean) or rewriting.

The same machinery makes crashes recoverable. Because “under construction” is a committed status (not just a live glow), a fresh agent with no memory of the crash can read the map, see exactly what was mid-build, and drive it to correct. Every committed write is atomic, so a crash mid-write leaves the old or the new file — never half.