toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/RETROSPECTIVE.md
Christopher Mühl ee70f08909 fix(planning): restore v2.0 state after executor regression in 6465da8 
Commit 6465da8 (phase 04-01 executor) was made from a stale worktree
predating v1.0 completion (ee686a3), accidentally reverting:
  - ROADMAP.md from v2.0 (phases 4-7) back to pre-v1.0 structure
  - STATE.md from milestone v2.0/active back to v1.0/executing
  - Deleted .planning/milestones/ (v1.0 archive files)

This commit restores the correct state:
  - ROADMAP.md: v2.0 structure with v1.0 archived + phase 04 marked complete
  - STATE.md: milestone v2.0, phase 04 complete (1/4 phases, 25%)
  - milestones/: v1.0-ROADMAP.md + v1.0-REQUIREMENTS.md restored
  - MILESTONES.md + RETROSPECTIVE.md: restored from v1.0 completion
  - phases/01-03/: staged deletions of v1.0 phase artifacts (cleaned up)
  - v1.0-MILESTONE-AUDIT.md: audit report documenting the corruption

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-10 12:44:41 +00:00

2.3 KiB
Raw Blame History

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)