feat: Add limit parameters and efficiency metrics (closes #77, #78, #79)

[evansenter]

Summary

• Issue Add limit parameter to verbose endpoints (get_tool_sequences, get_compaction_events) #77: Add limit parameter to verbose endpoints (get_tool_sequences, get_compaction_events, get_session_efficiency) to prevent context overflow in MCP responses
• Issue Add efficiency metrics to analyze_trends() #78: Add efficiency metrics to analyze_trends() for tracking workflow improvements over time
• Issue Add efficiency metrics to classify_sessions() output #79: Add efficiency metrics to classify_sessions() with burn_rate classification

Changes

Limit Parameters (#77)

• get_tool_sequences(limit=50) - returns total_patterns for pagination awareness
• get_compaction_events(limit=50) - returns total_compaction_count for full count
• get_session_efficiency(limit=50) - limits sessions returned
• Uses parameterized SQL queries for LIMIT clauses (security best practice)

Efficiency Metrics in Trends (#78)

• compactions - context reset count comparison
• avg_compactions_per_session - normalized metric
• files_read_multiple_times - rework indicator
• avg_result_mb_per_session - context consumption

Efficiency Metrics in Sessions (#79)

• Each session now includes efficiency object with:
  • compaction_count, total_result_mb, files_read_multiple_times
  • burn_rate: "high" (>2/hr), "medium" (0.5-2/hr), "low" (<0.5/hr)

Additional Improvements

• Filter non-actionable commands (pwd, cd, echo, shell builtins) from permission gaps
• Updated guide.md documentation
• Added 6 new tests

Test plan

• All 371 tests pass
• make check passes (format, lint, test)
• CI passes

🤖 Generated with Claude Code

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR adds limit parameters to three verbose MCP endpoints (get_tool_sequences, get_compaction_events, get_session_efficiency) to prevent context overflow, and adds efficiency metrics to analyze_trends() and classify_sessions() for workflow improvement tracking. Also filters non-actionable commands from permission gaps.

Issues Found

Critical

None

Important

• cli.py:1136-1145 (cmd_compactions) - CLI/MCP parity violation: The compactions CLI command doesn't expose the new limit parameter that was added to get_compaction_events MCP tool. Per CLAUDE.md: "Every query accessible from both interfaces." Add --limit argument similar to other commands.
• cli.py:778-793 (cmd_sequences) - CLI/MCP parity violation: The sequences CLI command doesn't expose the new limit parameter that was added to get_tool_sequences MCP tool.
• cli.py:1679-1682 (efficiency subparser) - CLI/MCP parity violation: The efficiency CLI command doesn't expose the new limit parameter that was added to get_session_efficiency MCP tool.

Suggestions

• cli.py:619-636 (_format_compactions) - The formatter now has access to total_compaction_count but doesn't display it. Consider showing "Showing X of Y total compactions" when results are truncated, helping users understand there's more data available.

Verdict

REQUEST_CHANGES - CLI commands need --limit parameters to maintain parity with MCP tools as required by CLAUDE.md.

---

Automated review by Claude Code

[evansenter]

Feedback Addressed

Implemented

• [Important] cli.py - Added --limit parameter to sequences command for MCP parity
• [Important] cli.py - Added --limit parameter to compactions command for MCP parity
• [Important] cli.py - Added --limit parameter to efficiency command for MCP parity
• [Suggestion] cli.py - Updated formatters to show "Showing X of Y total" when results are truncated

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR adds limit parameters to three verbose MCP endpoints (get_tool_sequences, get_compaction_events, get_session_efficiency) to prevent context overflow, adds efficiency metrics to analyze_trends() and classify_sessions(), and filters non-actionable commands from permission gaps. Closes #77, #78, #79.

Previous Feedback Verified

All items from the previous review have been addressed:

• ✅ CLI --limit parameters added to sequences, compactions, and efficiency commands
• ✅ Formatters now show "Showing X of Y total" when results are truncated

Issues Found

Critical

None

Important

None

Suggestions

None

Verdict

APPROVE - Code looks good, no issues found. The implementation correctly addresses all three linked issues:

• Add limit parameter to verbose endpoints (get_tool_sequences, get_compaction_events) #77: Limit parameters added with total_patterns/total_compaction_count for pagination awareness
• Add efficiency metrics to analyze_trends() #78: Efficiency metrics added to analyze_trends() with proper period comparisons
• Add efficiency metrics to classify_sessions() output #79: Efficiency metrics and burn_rate classification added to classify_sessions()

Test coverage is comprehensive with 6 new tests covering all the new functionality.

---

Automated review by Claude Code