# Project Retrospective

*A living document updated after each milestone. Lessons feed forward into future planning.*

## Milestone: v1.0 — MVP

**Shipped:** 2026-04-10
**Phases:** 3 | **Plans:** 5

### What Was Built
- Nix flake producing `claudebox` wrapper: bwrap sandbox with clearenv, env allowlist, tmpfs root, secret path hiding, git identity forwarding, comma/nix tool access
- CLI diagnostic modes: --check (environment validation), --dry-run (print bwrap command), --shell (debug shell)
- Pre-launch env audit with grouped sections, sensitive value masking, Y/n confirmation prompt
- SANDBOX.md generation and CLAUDE.md import management so Claude knows its sandbox constraints

### What Worked
- writeShellApplication with builtins.readFile pattern — shellcheck at build time, shell syntax highlighting in editors
- Rapid phase execution: Phase 1 in ~2 min, Phase 2 in ~4 min, Phase 3 in ~76 sec
- clearenv + allowlist approach caught all secret leakage by default
- readlink -f fix for NixOS symlinks was discovered and fixed in-phase without blocking

### What Was Inefficient
- REQUIREMENTS.md traceability table not updated during execution — 7 requirements showed "Pending" despite being complete
- Phase 3 context was gathered but not executed in the same session, requiring session continuity overhead

### Patterns Established
- readlink -f for all host-resolved binaries passed into bwrap (NixOS symlink chains)
- SANDBOX.md as separate file with @import in CLAUDE.md (keeps user content clean, sandbox instructions always fresh)
- export trick for shellcheck SC2034 when a variable is used in a later plan but not yet

### Key Lessons
1. On NixOS, every host binary path is a symlink chain through /etc/profiles/per-user/ — must resolve to real store paths before passing to bwrap
2. Conditional mounts needed for cross-distro support (/etc/static exists only on NixOS)

### Cost Observations
- Model mix: predominantly opus for execution
- Sessions: ~3 sessions across 2 days
- Notable: entire v1.0 MVP shipped in under 2 days of wall clock time

---

## Cross-Milestone Trends

### Process Evolution

| Milestone | Phases | Plans | Key Change |
|-----------|--------|-------|------------|
| v1.0 | 3 | 5 | Initial project — established sandbox patterns |

### Top Lessons (Verified Across Milestones)

1. (Will populate as more milestones complete)