feat(stereoscope): Slack bot for the Stereoscope Coffee workspace

[isaacsight]

What

Slack bot for the Stereoscope Coffee workspace, in two pieces under tools/stereoscope/:

1. Monday brief (brief.ts + post-brief.ts) — one post every Monday into a private ops channel: per-shop sales with week-over-week deltas, average ticket, labor as a percent of sales, then a single ranked "one thing to fix" and a short watch list. npm run stereoscope:brief dry-runs against the bundled 6-shop sample; --post sends via chat.postMessage.
2. Conversational presence (bot.ts) — Socket Mode bot, same architecture as tools/slack-bot.ts: per-thread history, Claude via the Supabase claude-proxy, answers DMs and mentions, threads replies in channels. npm run stereoscope:bot.

Why

Delivers the integration Stereoscope's ops lead checkmarked in the 2026-07-14 Slack DM, out of the 11-item menu pitched there: "every monday, one post in this slack — how all 6 shops did last week + the one thing to fix," with a sample to drop in the DM. The dry-run output is that sample.

How

• The brief composer is deterministic — every number is arithmetic over a WeekData JSON file (the intended feed is Zapier/cron producing that file from the POS export). No LLM in the loop, so the post is trustworthy and unit-testable. Findings are ranked in percentage points off plan, weighted by how directly the miss costs money: labor over target 1.5, sales decline 1.0 (2% floor), ticket drift 0.8 (3% floor); the top finding becomes "the one thing to fix," the rest plus manager notes become the Watch list. Missing metrics (no prior week, no labor tracking) render without their segment instead of erroring.
• The presence bot follows .claude/rules/backend.md (all Claude calls through supabase/functions/claude-proxy/), and its personality is scoped hard: never invents policy, recipes, prices, or numbers; routes wage/sales/personnel questions to managers and the private ops channel.
• Env vars are deliberately separate from the kernel workspace tokens (STEREOSCOPE_SLACK_BOT_TOKEN / STEREOSCOPE_SLACK_APP_TOKEN / STEREOSCOPE_BRIEF_CHANNEL) so a misconfigured shell can never cross-post between workspaces. No tokens or secrets committed; Slack app setup steps are in the README.
• sample-week.json carries invented numbers marked as such; four shop names are real, two are named placeholders to edit before demoing.

Testing

• npm run build passes (tsc portion; new files are tools-side and covered by the scoped strict check below)
• npm run test — npx vitest run tools/stereoscope/brief.test.ts: 14/14 pass
• npx tsc --noEmit passes (plus a scoped tsc --strict over the four new files)
• Tested manually with kbot in dev mode — n/a, this is a tools/ bot, not a kbot change; verified via the CLI dry run instead

Screenshots

Dry-run output (npm run stereoscope:brief):

*STEREOSCOPE — WEEK IN REVIEW*
Aug 17 – Aug 23

*All shops:* $157,580 (+0.3% vs prior week) · 12,960 transactions · avg ticket $12.16

*By shop*
• Newport Beach — $41,230 · +3.6% · ticket $13.21 · labor 29.0%
• Buena Park — $36,410 · -1.3% · ticket $12.82 · labor 29.0%
• Echo Park — $24,880 · -5.6% · ticket $11.79 · labor 31.0%
• Hollywood — $21,540 · +2.1% · ticket $11.40 · labor 33.4%
• Shop 5 (edit name) — $18,320 · +2.3% · ticket $11.38 · labor 29.0%
• Shop 6 (edit name) — $15,200 · +1.0% · ticket $10.94 · labor 29.1%

*The one thing to fix*
Echo Park — sales came in -5.6% vs the prior week ($24,880 against $26,350). Worth a look at what changed: hours, staffing, weather, or a menu shift.

*Watch*
• Hollywood labor at 33.4% (plan 30.0%)
• Echo Park labor at 31.0% (plan 30.0%)
• Echo Park: Grinder burrs due for replacement — ordered, lands Thursday

_Numbers computed from the weekly POS export. Reply in thread if something looks off._

🤖 Generated with Claude Code

---

Generated by Claude Code

[isaacsight]

CI note: the Web — Type-check & Build failure on e4ee0df was not this PR's diff. The root vitest suite globs tools/ableton/gen-coverage.test.mjs (added on main in 776fec1, which never had a CI run of its own), and vite cannot bundle the node:test builtin under the jsdom config — so suite collection failed while all 847 tests that could run passed, including this PR's 14.

Fix ported into this PR as 2ffc07c: the test bodies are plain test() + node:assert, so the runner import alone changes (vitest instead of node:test). All nine ableton tests now actually execute and pass; the full root suite is green locally at 58/58 files, 856/856 tests. The change no-ops if the same fix lands on main first.

---

Generated by Claude Code

[isaacsight]

Second inherited CI failure, also fixed: the e2e check failed on stacks.spec.ts ("the ledger lands on the real issue route") on both browsers. Root cause is on main, not this diff — ArchivePage never adds ka-scrollable-page, so the app shell's position: fixed; overflow: hidden body leaves /archive unable to scroll at all (the room's scroll-driven camera also never descends). The spec passed historically only because N°427 sat in the first viewport; ISSUE 429 (7ea6abe, landed on main without a CI run) added a volume above it and exposed the defect.

Fix pushed as 57b799f — the same one-effect opt-out the other twelve scrolling pages use. Verified locally: the failure reproduced on the prior head, all 6 stacks specs now pass on Desktop Chrome, no new failures in the full Desktop Chrome e2e run, tsc clean, 856/856 vitest. It no-ops if the same fix lands on main first.

---

Generated by Claude Code