.planning/REQUIREMENTS.md

@@ -0,0 +1,96 @@
+# Requirements: claudebox
+
+**Defined:** 2026-04-10
+**Core Value:** Secrets never enter the Claude Code environment. If a secret is accessible inside the sandbox, it's a bug.
+
+## v2.0 Requirements
+
+Requirements for v2.0 release. Each maps to roadmap phases.
+
+### Authentication
+
+- [ ] **AUTH-01**: User's existing Claude subscription works inside sandbox via host `~/.claude/.credentials.json` mounted read-write
+- [ ] **AUTH-02**: `ANTHROPIC_API_KEY` env var passed through when set on host (takes precedence over OAuth)
+
+### Instance Isolation
+
+- [ ] **INST-01**: Each project directory gets its own isolated `~/.claude` state (conversations, todos, history)
+- [ ] **INST-02**: Git worktrees of the same repo share the same instance directory
+- [ ] **INST-03**: Concurrent claudebox sessions in the same project are protected by flock
+- [ ] **INST-04**: `--gc` command cleans up instance directories for projects that no longer exist
+
+### Network Isolation
+
+- [ ] **NET-01**: `--network none` fully isolates network (offline mode, Nix daemon still works via socket)
+- [ ] **NET-02**: `--network inet` allows internet access but blocks LAN and Tailscale traffic
+- [ ] **NET-03**: `--network full` preserves current behavior (host network, default)
+- [ ] **NET-04**: `--network` CLI flag selects tier at launch
+- [ ] **NET-05**: `CLAUDEBOX_NETWORK` env var sets tier (CLI flag wins if both set)
+
+### Profiles
+
+- [ ] **PROF-01**: Named profiles loadable via `--profile foo` or `CLAUDEBOX_PROFILE=foo` (flag wins)
+- [ ] **PROF-02**: Profile defines env vars to pass through, extra mounts, and network tier
+- [ ] **PROF-03**: Profiles stored as JSON at `~/.claudebox/profiles/<name>.json`
+- [ ] **PROF-04**: `--list-profiles` shows available profiles
+- [ ] **PROF-05**: `--show-profile <name>` displays profile contents
+- [ ] **PROF-06**: Pre-launch audit extended to show active profile, network tier, and extra mounts
+
+## Future Requirements
+
+### Nix Package Injection
+
+- **PKG-01**: Profile `packages` field resolved via `nix build` and added to sandbox PATH
+- **PKG-02**: Package resolution cached to avoid startup latency on repeated launches
+
+### Profile Inheritance
+
+- **PROF-07**: Profile `extends` field to inherit from another profile
+
+### Instance Management
+
+- **INST-05**: Instance dir GC with dry-run mode
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Full nix develop devShell integration | Profile `packages` field covers 80% case; full devShell adds complexity |
+| Domain-level network allowlists | Three tiers (full/inet/none) cover actual use cases |
+| NixOS module form | Wrapper script derivation, not a services/programs module |
+| Shareability | Personal tool first, not designed for others yet |
+| Per-profile SANDBOX.md overrides | Breaks the security invariant — one SANDBOX.md for all |
+| Storing secret values in profile files | Profiles reference env var names, not values |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 4 | Pending |
+| AUTH-02 | Phase 4 | Pending |
+| INST-01 | Phase 5 | Pending |
+| INST-02 | Phase 5 | Pending |
+| INST-03 | Phase 5 | Pending |
+| INST-04 | Phase 5 | Pending |
+| NET-01 | Phase 6 | Pending |
+| NET-02 | Phase 6 | Pending |
+| NET-03 | Phase 6 | Pending |
+| NET-04 | Phase 6 | Pending |
+| NET-05 | Phase 6 | Pending |
+| PROF-01 | Phase 7 | Pending |
+| PROF-02 | Phase 7 | Pending |
+| PROF-03 | Phase 7 | Pending |
+| PROF-04 | Phase 7 | Pending |
+| PROF-05 | Phase 7 | Pending |
+| PROF-06 | Phase 7 | Pending |
+
+**Coverage:**
+- v2.0 requirements: 17 total
+- Mapped to phases: 17
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-04-10*
+*Last updated: 2026-04-10 after initial definition*