non-linear-docs/06a-ALPHA-SCOPE.md

Non-Linear: v0.1-alpha Scope

Validation Goal

Can a team of 3-5 people use this as their sole tracker for two weeks without falling back to another tool?

Ship the smallest thing that tests whether graph-native structure + repo-inferred skeleton + agent graph traversal is better than Linear for a small team. Everything else can wait.

What Ships

Data Model

• Two node types: Components (skeleton, map to code) and Issues (work, flow through statuses)
• Decomposition tree: strict parent→child hierarchy, single root, single project
• Lateral links: blocks and relates_to only
• Statuses: backlog, todo, in_progress, in_review, done, cancelled (permissive transitions)
• Labels: freeform tags, no enforced taxonomy
• Complete change history: every mutation stored with actor + timestamp

No user-facing "layers" concept. The 4-layer architecture is an internal design pattern — in alpha, there is simply structure and work.

Repository Integration

This is the differentiator. It must ship.

• Connect repos: OAuth to GitHub/GitLab, select repos for a project
• Skeleton inference: AI scans repo structure → proposes component tree → user adjusts → skeleton committed
• Commit-message linking: fixes NL-42 / refs NL-42 triggers status change or surfaces in activity feed (regex parsing via webhook)

Views

Two views, not four:

• Focus widget: Node + parent + children + breadcrumbs + detail panel + comments + change history. Primary daily-use view.
• Flat list / Kanban board: Issues listed or grouped by status columns. Sorting, filtering by label/assignee/status. Bulk status change.

A simple collapsible tree sidebar replaces the full layered overview graph visualization.

Interaction

• Command palette (Cmd+K): Fuzzy search across nodes and actions. Non-negotiable for keyboard-first.
• Keyboard navigation: Alt+↑/↓/←/→ for tree traversal in focus widget.
• Confirmation dialogs for destructive/structural operations (replaces full plan-then-apply previews).

Triage

• Inbox: Issues without a parent land here. Triage = assign a parent via command palette or drag.

Auth & Permissions

• Authentik OIDC: Login for humans
• API tokens: Bearer tokens for agents, issued manually
• Three hardcoded roles:
  • Owner — all actions
  • Member — all except delete and manage members
  • Agent — read + comment + change status + triage (assign parent)

No policy engine. No subtree scoping. No custom roles.

Agent API

Read operations:

GET /api/v1/nodes/{id}
GET /api/v1/nodes/{id}/children
GET /api/v1/nodes/{id}/parent
GET /api/v1/nodes/{id}/links
GET /api/v1/nodes/{id}/path
GET /api/v1/projects/{id}/root
GET /api/v1/projects/{id}/inbox

Write operations:

POST   /api/v1/nodes/{id}/comments
PATCH  /api/v1/nodes/{id}/status
PATCH  /api/v1/nodes/{id}/parent

Queries:

GET /api/v1/projects/{id}/nodes?status=todo&assignee=agent-1&unblocked=true

Webhooks (minimal): Register URL + events. Single delivery attempt, log failures. No retry logic, no HMAC signatures.

Real-Time

• Centrifugo: Push status changes, new nodes, new comments to connected clients via project:{id} channel.

Comments

• Flat comment stream per node. Markdown body. Author + timestamp.

Infrastructure (~8 containers)

api          (FastAPI + uvicorn)
frontend     (Vue 3 + Vite)
postgres
redis
centrifugo
caddy        (reverse proxy + automatic TLS)
authentik    (OIDC provider)
authentik-db (Authentik's Postgres)

• Search: Postgres tsvector full-text search (no Meilisearch)
• File storage: None (no uploads in alpha — links in descriptions suffice)
• Secrets: Environment variables / Docker secrets (no Vault)
• Observability: Structured JSON logs + docker logs (no Prometheus/Grafana/Loki/Tempo)
• Deployment: Single Docker Compose file, one machine. Dev = production topology.

What Does NOT Exist in Alpha

Feature	Reason to Defer
Layer 3 (Code Connections)	Complex inference, unclear daily value until skeleton is stable
Layer 4 (Artifacts)	A URL in the description works for 2 weeks
Layer toggles in UI	No Layer 3/4 data to toggle
Cycles	Time-boxing is nice-to-have, not thesis-critical
Notifications (email/push)	In-app real-time is enough for a co-located/online team
Full policy engine	Not testing permission granularity
Natural language node creation	Manual creation via palette is fast enough
Plan-then-apply previews	Confirmation dialog suffices
Comment reactions	Zero impact on validation
Observability stack	Structured logs are enough
Secrets management (Vault)	Env vars for single-node deployment
Tauri desktop wrapper	Browser-only
Meilisearch	Postgres tsvector is sufficient for small graphs
MinIO / file uploads	Descriptions can link to external files
Pagination	Graphs will be small (<500 nodes)

Success Criteria

• Team uses Non-Linear as sole tracker for 2+ weeks
• No fallback to Linear/spreadsheet for any workflow
• At least one repo connected with inferred skeleton
• Agent produces at least 1 useful action per day
• Users create trees with 3+ depth levels
• Command palette action <200ms, view transitions <100ms

After Alpha Validates

Features flow from feedback, not speculation:

• Users want to attach design files → add Artifacts (Layer 4)
• Users want dependency visibility → add Code Connections (Layer 3)
• Agents need subtree isolation → add policy engine
• Teams are distributed → add notifications (email/push)
• Graph viz is too limited → build the layered overview
• Projects grow large → add pagination, Meilisearch, cycles