chore: vertical slice architecture with Supermodel enforcement

Architecture (docs/architecture.md):
- Strict vertical slices — slices must not import each other
- Shared kernel: internal/api, config, cache, ui, build
- Slices: analyze, deadcode, blastradius, graph, auth
- cmd/ is pure wiring (cobra → slice handler), may import any internal/

Scaffold:
- internal/{api,config,cache,ui}/doc.go — shared kernel stubs
- internal/{analyze,deadcode,blastradius,graph,auth}/doc.go — slice stubs
  Each doc comment states the rule and lists permitted kernel imports.

Enforcement (scripts/check-architecture/main.go):
- Zips repo with git archive, uploads to Supermodel API (/v1/supermodel)
- Parses dependency graph (nodes + IMPORTS/WILDCARD_IMPORTS relationships)
- Resolves both file-path and import-path node formats to "internal/X"
- Fails with a clear violation report if any slice imports another slice

CI (.github/workflows/architecture.yml):
- Triggers on PRs touching internal/, cmd/, or main.go
- Skips gracefully when SUPERMODEL_API_KEY is absent (fork PRs)
- `make arch-check` runs it locally

Secret required:
  SUPERMODEL_API_KEY — API key from api.supermodeltools.com

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: greynewell

.github/workflows/architecture.yml

@@ -0,0 +1,39 @@
+name: Architecture
+
+on:
+  pull_request:
+    paths:
+      - 'internal/**'
+      - 'cmd/**'
+      - 'main.go'
+      - 'scripts/check-architecture/**'
+  push:
+    branches: [main]
+    paths:
+      - 'internal/**'
+      - 'cmd/**'
+      - 'main.go'
+
+jobs:
+  vertical-slice:
+    name: vertical slice check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Check vertical slice architecture
+        env:
+          SUPERMODEL_API_KEY: ${{ secrets.SUPERMODEL_API_KEY }}
+        run: |
+          if [ -z "$SUPERMODEL_API_KEY" ]; then
+            echo "::warning::SUPERMODEL_API_KEY not set — skipping architecture check (fork PR?)"
+            exit 0
+          fi
+          go run ./scripts/check-architecture

Makefile

@@ -50,6 +50,11 @@ tidy:
 clean:
 	rm -rf $(OUTDIR) coverage.out
 
+## arch-check: validate vertical slice architecture via Supermodel API
+arch-check:
+	@[ -n "$$SUPERMODEL_API_KEY" ] || (echo "error: SUPERMODEL_API_KEY is not set" && exit 1)
+	go run ./scripts/check-architecture
+
 ## release-dry: dry-run GoReleaser (builds all platform binaries locally)
 release-dry:
 	goreleaser release --snapshot --clean

docs/architecture.md

@@ -0,0 +1,87 @@
+# CLI Architecture — Vertical Slice
+
+## Guiding principle
+
+Each user-facing feature is a **vertical slice**: a self-contained package that
+owns its own command wiring, business logic, API calls, and output formatting.
+Slices are allowed to share infrastructure (the kernel) but are **forbidden from
+depending on each other**.
+
+This keeps features independently changeable. Adding `blast-radius` cannot break
+`dead-code`. Refactoring `auth` cannot affect `analyze`.
+
+## Package map
+
+```
+main.go                      entry — calls cmd.Execute(), nothing else
+
+cmd/                         wiring layer — cobra commands that delegate to slice handlers
+  root.go                    root command, global flags
+  version.go                 version subcommand (trivial, no handler)
+  analyze.go   ─────────────────────────────────────────────┐
+  deadcode.go  ──────────────────────────────────────────┐  │
+  blastradius.go ────────────────────────────────────┐   │  │
+  graph.go     ──────────────────────────────────┐   │   │  │
+  auth.go      ──────────────────────────────┐   │   │   │  │
+                                             │   │   │   │  │
+internal/                                    │   │   │   │  │
+  ┌──────────────── SHARED KERNEL ───────┐   │   │   │   │  │
+  │ api/      HTTP client primitives     │   │   │   │   │  │
+  │ config/   ~/.supermodel/config.yaml  │◄──┘   │   │   │  │
+  │ cache/    local graph cache          │◄──────┘   │   │  │
+  │ ui/       output, tables, spinners   │◄──────────┘   │  │
+  │ build/    version/commit/date vars   │◄──────────────┘  │
+  └──────────────────────────────────────┘                  │
+                                                            │
+  ┌──────────────── VERTICAL SLICES ─────────────────────┐  │
+  │ analyze/      upload & full analysis pipeline        │◄─┘
+  │ deadcode/     dead code detection                    │
+  │ blastradius/  downstream impact analysis             │
+  │ graph/        graph display and export               │
+  │ auth/         login / logout / token storage         │
+  └──────────────────────────────────────────────────────┘
+```
+
+## Rules
+
+| From → To         | Allowed? |
+|-------------------|----------|
+| `main.go` → `cmd/`                     | ✅ |
+| `cmd/` → any `internal/`               | ✅ (wiring) |
+| `internal/<slice>` → `internal/kernel` | ✅ |
+| `internal/<slice>` → `internal/<slice>`| ❌ **FORBIDDEN** |
+| `internal/kernel` → `internal/<slice>` | ❌ **FORBIDDEN** |
+
+**Shared kernel packages** (`internal/api`, `internal/build`, `internal/cache`,
+`internal/config`, `internal/ui`) must contain zero business logic. They are
+pure infrastructure — HTTP primitives, config loading, formatting utilities.
+
+Any package under `internal/` that is NOT in the kernel list is treated as a
+slice and subject to the cross-slice import ban.
+
+## Adding a new feature
+
+1. Create `internal/<feature>/` with `command.go`, `handler.go`, `types.go`.
+2. Register the cobra command in `cmd/<feature>.go` by calling into the slice.
+3. Do not import any other slice from the new package.
+4. The architecture check in CI will reject the PR if the rule is violated.
+
+## Adding a new kernel package
+
+1. Add the package under `internal/<name>/`.
+2. Add `"internal/<name>": true` to `sharedKernel` in
+   `scripts/check-architecture/main.go`.
+3. Keep it free of business logic.
+
+## Enforcement
+
+The `.github/workflows/architecture.yml` workflow runs on every PR that touches
+`internal/`, `cmd/`, or `main.go`. It zips the repository, sends it to the
+[Supermodel API](https://api.supermodeltools.com), parses the dependency graph,
+and fails the build if any cross-slice `IMPORTS` relationship is found.
+
+Run locally:
+
+```sh
+SUPERMODEL_API_KEY=<key> go run ./scripts/check-architecture
+```

internal/analyze/doc.go

@@ -0,0 +1,8 @@
+// Package analyze implements the `supermodel analyze` command.
+// It uploads a repository ZIP to the Supermodel API, runs the full analysis
+// pipeline, and caches the resulting graph locally.
+//
+// This is a vertical slice. It must not import any other slice package.
+// It may import from the shared kernel: internal/api, internal/cache,
+// internal/config, internal/ui, internal/build.
+package analyze

internal/api/doc.go

@@ -0,0 +1,7 @@
+// Package api provides the HTTP client and base request primitives for the
+// Supermodel API. It handles authentication headers, idempotency keys, error
+// parsing, and response decoding.
+//
+// This is a shared kernel package. It must contain no business logic.
+// Slice packages under internal/ may import it freely.
+package api

internal/auth/doc.go

@@ -0,0 +1,8 @@
+// Package auth implements the `supermodel login` and `supermodel logout` commands.
+// It handles GitHub OAuth, API key retrieval, and secure token storage in
+// the user's config file.
+//
+// This is a vertical slice. It must not import any other slice package.
+// It may import from the shared kernel: internal/api, internal/cache,
+// internal/config, internal/ui, internal/build.
+package auth

internal/blastradius/doc.go

@@ -0,0 +1,8 @@
+// Package blastradius implements the `supermodel blast-radius` command.
+// Given a file or function, it queries the Supermodel API call graph to
+// show which other files and functions would be affected by a change.
+//
+// This is a vertical slice. It must not import any other slice package.
+// It may import from the shared kernel: internal/api, internal/cache,
+// internal/config, internal/ui, internal/build.
+package blastradius

internal/cache/doc.go

@@ -0,0 +1,7 @@
+// Package cache manages the local graph cache stored under ~/.supermodel/cache/.
+// Graphs are keyed by the SHA-256 hash of the uploaded repository ZIP, matching
+// the content-addressed scheme used by the Supermodel API.
+//
+// This is a shared kernel package. It must contain no business logic.
+// Slice packages under internal/ may import it freely.
+package cache

internal/config/doc.go

@@ -0,0 +1,7 @@
+// Package config manages the user's Supermodel configuration stored at
+// ~/.supermodel/config.yaml. It handles loading, saving, and validating
+// config values such as the API key, default output format, and API base URL.
+//
+// This is a shared kernel package. It must contain no business logic.
+// Slice packages under internal/ may import it freely.
+package config

internal/deadcode/doc.go

@@ -0,0 +1,8 @@
+// Package deadcode implements the `supermodel dead-code` command.
+// It calls the Supermodel API to identify functions and files with no callers,
+// then renders the results as a table or JSON.
+//
+// This is a vertical slice. It must not import any other slice package.
+// It may import from the shared kernel: internal/api, internal/cache,
+// internal/config, internal/ui, internal/build.
+package deadcode