Add get_pnl + get_capacity MCP tools (completes P1a read layer)

[hhff]

What

The final two P1a read tools from the Stacksbot roadmap — all eight P1a read tools are live after this.

• `get_pnl` — Profit & Loss (revenue / COGS / expenses / net revenue / profit margin) per enterprise from the nightly-synced QBO P&L reports. Params: `enterprise` (default Sanctuary), `accounting_method` (cash/accrual), `start_date`/`end_date` (default most recent synced period), `vertical` (default All). Unblocks the Financial Reports auto-writer (automation Include contractors in OKRs #9).
• `get_capacity` — per-person resourcing from the nightly utilization reports: each active person's sellable / billable / internal / time-off / unsold hours, utilization rate, and `benched` flag. Params: `studio`, `gradation` (default month, most-recent period). Unblocks bench-capacity → outreach (P4) and capacity watch.

Safety

• Never a live external API call. `get_pnl` queries persisted `QboProfitAndLossReport` rows directly and never calls `find_or_fetch_for_range` (which fires live QBO fetches when a row is absent) — locked with a `.expects(:find_or_fetch_for_range).never` test. `get_capacity` reads persisted utilization reports only.
• In-tool margin. The model's `data_for_enterprise` computes `profit_margin` but discards the result (returns 0 — a latent model bug, noted for a separate PR); `get_pnl` computes margin itself from the model's sound revenue/net bucketing.
• Read-only annotations; skip+warn+Sentry on per-row failures; no schema/gem/model changes.

⚖️ For your review: capacity per-person data boundary

`get_capacity` is the most individual-level data any Stacks MCP tool exposes — per-person booked hours. I defaulted to named, resourcing-framed (email + hours + benched flag) because the roadmap explicitly names "per-person utilization" as a `get_capacity` deliverable, `get_studio_health` excluded utilization specifically because it's get_capacity's surface, and "who's free to staff" is unactionable without names. The payload emits no comp / salary / performance-evaluative fields — raw resourcing hours + benched status only; archived people excluded; the wall on comp/HR/1:1 content is untouched. If you'd prefer bench-only names or aggregate-only, say so and I'll re-cut it.

Process

Spec-first (design + plan in `docs/superpowers/`, capacity boundary flagged ⚖️), subagent-driven development in an isolated worktree, per-task reviews (get_pnl caught a missing `.distinct` dedup, reproduced against fixtures + fixed; get_capacity clean first pass), whole-branch final review (verdict: ready; its two worthwhile items — no-QBO-account guard, consistent empty-period shape — applied pre-PR). A multi-round adversarial review loop follows; findings land as additional commits.

Tests

Covering suites: 15 runs, 55 assertions, 0 failures. Full suite: 611 runs, 1454 assertions, 0 failures (19 pre-existing skips). Coverage: P&L bucketing + in-tool margin, never-fetch invariant (both tools), accounting-method/most-recent-period selection, range-miss lists available, unknown-enterprise (deduped) + no-QBO-account + invalid-method errors; capacity column mapping + benched flag, archived exclusion, most-recent period, studio scoping, invalid-gradation/unknown-studio errors, empty-period shape; registry (11 tools) + `tools/call` round-trips.

🤖 Generated with Claude Code

[hhff]

Self-review loop converged (10 rounds of high-effort multi-agent adversarial review).

This slice needed more rounds than the prior three — the QBO P&L period-selection semantics turned out to be genuinely subtle, and the loop was worth every round. What it caught, in order of severity:

• round 1: an unrescued 500 on a report with the schema-default empty data; a silently-zeroed P&L for an unknown vertical.
• round 2: forced the decision to cut the vertical param rather than ship silently-incomplete per-vertical numbers (model's below-the-line bucketing gap).
• round 7 (the big one): a design flaw my spec, plan, and six prior rounds all missed — QboAccount syncs monthly + quarterly + yearly reports into one table with no discriminator and a future-dated current-year row, so "most recent" returned a whole-year P&L instead of the latest month. Fixed with a period_type param + span classification.
• round 8: a deeper layer — the in-progress current month (future-dated, ~few days of data) still won; now defaults to the most recent completed period (ends_at <= today).
• rounds 3–6, 9: NULL/non-Hash/malformed-data guards, multi-account scoping, a NULL-archived consistency bug (a regression from my own round-5 optimization, reverted), and error-message/label polish.

Rounds 9 and 10 returned zero wrong-data/crash findings — the P&L numbers and capacity roster are correct across a large matrix of real data-shape edges; the tail was error-message wording only. Round 10 was a genuine clean (all four finder angles completed).

Deferred (documented in the spec / code): three shared data_for_enterprise model defects (discarded margin, per-vertical below-the-line bucketing, find_rows substring match) → a separate model-fix PR so the tool and admin dashboard stay consistent; cross-QBO-realm P&L aggregation (has_one is the domain intent); the accounting-method-fallback (erroring is more honest than silently substituting a different period).

⚖️ Still for your call (PR body): the get_capacity per-person data shape — named/resourcing-framed by default, no comp/performance fields.

Full suite green (627 runs, 0 failures; 19 pre-existing skips). CI check in progress — will confirm before this is ready to merge.