Phase 2: analysis layer (analyze.js), cache guard, log hygiene

- analyze.js: burn rate, weekly reconstruction, cycle stagger, rotation
  rank, underspend alerts, log prune with weekly archive
- logger.js: getCachedRun(maxAgeMinutes) — skip probing if recent data exists
- monitor.js: cache guard at wake — 20-min dedup, zero extra API calls
- test.js: fix type assertion for gemini-api/xai-api providers (+5 passing);
  add 14 new tests for cache guard and analyze.js (162 total, all green)
- docs/analyze.md: usage reference

Co-authored-by: Hannibal Smith <hannibal@trentuna.com>

docs/analyze.md

@@ -0,0 +1,54 @@
+# analyze.js — Token Monitor Analysis CLI
+
+Reads accumulated JSONL logs from `~/.logs/token-monitor/` and produces burn
+rates, weekly stats, reset schedule, and rotation recommendations.
+
+## Usage
+
+```
+node analyze.js                         # full report (default)
+node analyze.js --burn-rate             # burn rate per account only
+node analyze.js --weekly                # weekly budget reconstruction
+node analyze.js --stagger               # reset schedule (next 48h)
+node analyze.js --rotation              # rotation recommendation only
+node analyze.js --json                  # JSON output (all sections)
+node analyze.js --provider team-nadja   # filter to one provider
+node analyze.js --prune                 # prune logs older than 30 days
+node analyze.js --prune --dry-run       # dry run — show what would be pruned
+```
+
+## Output sections
+
+**Burn Rate** — delta analysis of 7d utilization over time, projected
+exhaustion at current rate. Requires ≥ 2 data points per provider.
+
+**Reset Schedule** — providers resetting within the next 48 hours, sorted
+ascending by time to reset.
+
+**Weekly Reconstruction** — peak and average 7d utilization per provider per
+ISO week. Shows exhaustion events (status=rejected).
+
+**Rotation Recommendation** — ranked provider list. Rules in priority order:
+1. Invalid key → bottom (unusable)
+2. Maxed/rejected → deprioritize; soonest reset wins tiebreaker
+3. Dormant → reserve for cycle staggering
+4. Active: rank by headroom (1 - utilization_7d)
+
+**Underspend Alerts** — active accounts with ≥ 40% of 5h window unused and
+< 2h until reset. These tokens expire unused — boost them.
+
+## Log format
+
+Input: `~/.logs/token-monitor/YYYY-MM-DD.jsonl` — one JSON object per line.
+
+Pruned archives: `~/.logs/token-monitor/weeks/YYYY-WNN.json` — weekly
+aggregates with peak/avg utilization and sample counts.
+
+## Cadence
+
+Logs are written by `monitor.js` at each Vigilio wake (max once per 20
+minutes — cache guard prevents double-logging within a session). Expected:
+~15–20 data points/day per active provider, ~100–140/week.
+
+At target cadence, log footprint is < 1MB/month. --prune trims files older
+than 30 days after archiving them into weekly summaries.

docs/missions/token-monitor-phase2-gates.md

@@ -0,0 +1,54 @@
+## Pre-Build Gate
+
+**Verdict: PASS**
+
+**Gate assessed:** 2026-04-05 (assessment #7 — replaces #6)
+**Mission:** token-monitor-phase2 (trentuna/token-monitor#1)
+**Assessor:** Amy Allen
+
+---
+
+### What I checked
+
+1. **Mission spec (Forgejo #1):** ✅ Complete. Four deliverables with operational outcomes: cache guard, analyze.js with six subcommands, log hygiene with prune, token-status.sh integration.
+
+2. **Architecture (Hannibal's comment on #1):** ✅ Thorough. Function signatures (`getCachedRun`, `loadLogs`, `computeBurnRate`, `reconstructWeekly`, `cycleStagger`, `underspendAlerts`, `rotationRank`), CLI interface, output formats, internal module contracts all specified. Single new file + minimal mods to existing code. Low blast radius.
+
+3. **Objective clarity:** ✅ Unambiguous. Each deliverable has specified behavior and output format.
+
+4. **Success criteria testability:** ✅ Five explicit assertions in Hannibal's architecture — all concrete and automatable:
+   - `node analyze.js` exits 0 with non-empty output from existing log data
+   - `node analyze.js --rotation` outputs a ranked list
+   - Two consecutive `node monitor.js --json` within 20 min: second returns cached data, no new JSONL entry
+   - `node analyze.js --prune --dry-run` reports files without deleting
+   - `node test.js` still passes
+
+5. **Test baseline (prior Concern 1):** ✅ **RESOLVED.** `test.js:102` whitelist now includes `'gemini-api'` and `'xai-api'`. All 146 tests pass (verified just now). The "tests still pass" criterion is now meetable.
+
+6. **Recon completeness:** ✅ No external unknowns. All data sources are local JSONL files (102 entries across 2 days — sufficient for immediate testing). No Face recon needed. `token-status.sh` already logs by default (no `--no-log` flag present).
+
+7. **Role assignments:** ✅ Explicit in both the issue and architecture comment.
+
+8. **Brief quality per mission-standards.md:**
+   - [x] Objective describes operational outcome (trend-line intelligence, not just "a script")
+   - [x] Success criteria are testable assertions (5 concrete checks)
+   - [x] Role assignments name who does what
+   - [x] No agent-affecting changes requiring self-verification
+
+### What's clean
+
+- Spec + architecture together form one of the cleanest briefs I've reviewed
+- Function signatures, output formats, internal module contracts all specified
+- Low blast radius: one new file (`analyze.js`), two small mods (`logger.js`, `monitor.js`), one external mod (`token-status.sh`)
+- No external dependencies or API unknowns
+- 102 real log entries in `~/.logs/token-monitor/` for immediate testing
+- Stealth constraint clearly specified with sound cache guard design
+- Prior blocking concern (test baseline) is now resolved
+
+### Outstanding items
+
+None. B.A. is clear to build.
+
+---
+
+*Triple A reporting. Seventh assessment — the test baseline is fixed, all 146 pass, and the spec remains excellent. No concerns remain. Hannibal's architecture is thorough and B.A. has everything he needs. PASS.*