docs(02-01): complete flag parsing and CLI modes plan

.planning/phases/02-env-audit-and-cli-polish/02-01-SUMMARY.md

@@ -0,0 +1,57 @@
+---
+phase: 02-env-audit-and-cli-polish
+plan: 01
+subsystem: cli
+tags: [flag-parsing, dry-run, check-mode, cli-ux]
+dependency_graph:
+  requires: []
+  provides: [SKIP_AUDIT, DRY_RUN, CHECK_MODE, CLAUDE_ARGS]
+  affects: [02-02]
+tech_stack:
+  added: []
+  patterns: [while-shift-flag-parsing, early-exit-modes]
+key_files:
+  modified: [claudebox.sh]
+decisions:
+  - "export SKIP_AUDIT to satisfy shellcheck SC2034 (unused variable) since Plan 02 consumes it"
+metrics:
+  duration: 2min
+  completed: "2026-04-09T15:11:34Z"
+  tasks: 3
+  files: 1
+---
+
+# Phase 02 Plan 01: Flag Parsing and CLI Modes Summary
+
+Refactored claudebox flag parsing from single-flag for/shift/break to multi-flag while/shift with CLAUDE_ARGS accumulator, then added --check and --dry-run early-exit diagnostic modes.
+
+## Completed Tasks
+
+| # | Task | Commit | Key Changes |
+|---|------|--------|-------------|
+| 1 | Refactor flag parsing to while/shift with CLAUDE_ARGS | `07096ae` | Replaced for-loop with while/shift, added SKIP_AUDIT/DRY_RUN/CHECK_MODE flags, CLAUDE_ARGS accumulator |
+| 2 | Add --dry-run mode | `3903667` | Prints full bwrap command with all env and mount flags to stderr, exits 0 |
+| 3 | Add --check mode | `cc6bd5b` | Verifies bwrap/claude/git/curl/nix binaries, ~/.claudebox dir, ANTHROPIC_API_KEY presence |
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] shellcheck SC2034 for SKIP_AUDIT**
+- **Found during:** Task 3 (nix build verification)
+- **Issue:** shellcheck flagged SKIP_AUDIT as unused since Plan 02 hasn't consumed it yet
+- **Fix:** Added `export SKIP_AUDIT` after flag parsing loop with comment noting Plan 02 dependency
+- **Files modified:** claudebox.sh
+- **Commit:** `cc6bd5b`
+
+## Verification Results
+
+- `grep -c CLAUDE_ARGS claudebox.sh` returns 5 (declaration + 2 accumulations + 2 usages)
+- All three flag variables (SKIP_AUDIT, DRY_RUN, CHECK_MODE) present in claudebox.sh
+- `nix build` succeeds (shellcheck validation passes)
+
+## Threat Surface Scan
+
+T-02-02 mitigated: --check mode only tests `[[ -v ANTHROPIC_API_KEY ]]` for presence, never prints the value.
+
+## Self-Check: PASSED