# 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 (~10 containers)

```
api          (FastAPI + uvicorn)
frontend     (Vue 3 + Vite)
worker       (Taskiq — webhook delivery, skeleton inference)
neo4j
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