mercury-agent 0.16.0 → 0.16.2

package/docs/goals/football-reporter-profile/roadmap.md

@@ -0,0 +1,196 @@
+# Roadmap: Football Reporter Profile
+
+**Goal**: [football-reporter-profile](goal.md)
+**Last updated**: 2026-08-22 (M2.3 shipped; audit extension M2.3–M2.5, D-016–D-018; napkin revisit — M2.3 re-cut, D-019)
+
+> Sequence chosen by the owner on 2026-08-20: (1) profile + one editorial
+> layer → (2) deterministic feed → (3) proof of quality, with a parallel bug
+> track for anything unrelated, then (4) regression + re-audit + monitoring.
+
+## Milestones
+
+### Milestone 1: One owner for the editorial rules, and an article worth tapping
+> M1.1 is zero code change to the bot and observable on the live group within
+> 48 h; after it every football rule lives in the repo, deploys by script, and
+> a `check` proves no drift. M1.2 redesigns the daily article (Telegraph page
+> + fuller in-chat summary, D-005/D-010) — the one code-bearing story in this
+> milestone (`longview`).
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M1.1 | Space profile folder + `AGENTS.md` editorial standard + apply/check/dump script; slim task prompts; delete `club-coverage` | football-reporter-space-profile | — | done |
+| M1.2 | Daily article redesign: top-tier Telegraph article (headline, standfirst, sections, pull-quote, certainty box, sources), author-supplied fuller chat summary in `longview` (F3) | daily-article-redesign | M1.1 | done |
+
+**Checkpoint:** after two daily articles and ~10 scans on the new `AGENTS.md`:
+no `"Done."`/filler reached the group; every posted item shows `(source)` and
+a date; 0 emoji in scheduled output; `club-coverage` is gone from the prefs
+panel; `scripts/space-profile.ts check` is clean; the redesigned page passes
+the visual checklist on a phone, the chat summary carries the key facts, and
+the group's reaction to the first two articles is recorded in the goal's notes.
+
+> **Checkpoint passed 2026-08-21** on one article rather than two, by owner's
+> decision — M2.1 depends on M1.1 only, so nothing about feed-watch waits on the
+> second article. Evidence from the first 24 h after the deploy (ledger runs #1
+> and #2, full detail in `docs/pending-verification.md`):
+>
+> - **Passed:** `NO_UPDATE` fired unattended on the 00:00 scan (9-char reply,
+>   `outcome=no_update`, nothing posted); the 09:00 article carries 1 `#` title,
+>   8 `##` sections, exactly 1 `>>` pull-quote, single-star bold only, 0 emoji
+>   and 0 exclamation marks; the summary block is 452 chars / 4 lines, inside
+>   both the 900 cap and the 3–6 band; one model call per run, confirmed against
+>   `token_usage`; `space-profile check` clean on `apply` and on the next sync;
+>   `club-coverage` gone.
+> - **Failed, and folded into M3.1's lint per [D-014](decisions.md):** no item
+>   carries a publication date — on the scan *and* on the article summary, though
+>   the article body of the same run dated 5 items.
+> - **Still open:** the Telegraph page cannot be confirmed from the host (since
+>   M1.2 the `storedReply` seam stores the raw article, so the delivered link is
+>   in no table); the phone RTL check; the group's reaction; the second article.
+> - **Baseline for M2:** scan $0.456/run, article $0.769/run; whole-project daily
+>   spend $7.53 (08-19) and $7.19 (08-20), against M2's ~$5.30/day direction.
+
+### Milestone 2: A deterministic feed in front of the model
+> Scans stop being blind; empty scans cost nothing; a fallback-leg run never
+> posts.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M2.1 | Feed Watch — host-side poller, digest into the article, verify one-shots (existing spec, absorbed) | feed-watch | M1.1 | done (merged `e07b239` 2026-08-21; **deploy not yet run** — runbook in `pending-verification.md`) |
+| M2.2 | Scheduled task model-leg policy: primary-or-skip for research runs (F2) | scheduled-task-model-leg-policy | — | deferred until after M3.1 (D-015) |
+| M2.3 | Reporter notebook, re-cut 2026-08-21 (D-019): topic notes are napkin-shaped **episodes** the profile seeds once and napkin maintains nightly, written in-turn before posting; seeded `MEMORY.md` for standing facts; priorities tie-break in `AGENTS.md`; `workspace_seed` in `space-profile`; per-space distillation addendum in napkin; member perms and stale-note hygiene (audit R1/R6/R7, D-016, D-019) | reporter-notebook | M1.1 | done (merged 2026-08-22; **deploy not yet run** — runbook in `pending-verification.md`) |
+| M2.4 | One voice per space: `persona.exclusive` drops the global character and global `AGENTS.md` for a space that owns its standard; platform-prompt capability paragraphs gated on the caller's permissions (audit R2, D-017) | one-voice-per-space | — | in-progress (worktree `worktree-feature-one-voice-per-space`; host; image rebuild) |
+| M2.5 | Chat window holds conversation, not procedure (scheduled prompts out of the turn count, no halving on swipe-reply); silence is a legal chat reply (audit R3/R4, D-018) | chat-window-and-silence | — | backlog (host) |
+
+> **Revisit 2026-08-21 — napkin works now** (`docs/notes/napkin-revisit-2026-08-21.md`). **Approved by the owner the same day ([D-019](decisions.md)):** M2.3 re-cut so the topic notes are napkin-maintained episodes under `knowledge/episodes/` (the only injected dir) that the profile seeds once, plus a per-space distillation addendum. Nothing removed; M2.4/M2.5/M3.x unchanged. Idea parked: `docs/ideas/napkin-member-notes.md`.
+
+> **M2.2 is largely pre-empted by the 2026-08-20 Opus pin.** `runtime.ts:1871`
+> turns `space_config['model.active']` into a **one-element** `MODEL_CHAIN`
+> for the container — its own comment reads "eliminates automatic
+> fallback" — and all 6 spaces carry that row. So no run of any task in any
+> space can reach a fallback leg today, and a leg failure already surfaces as
+> a task error that retries and then reports, posting nothing. What M2.2 would
+> still add is (a) the guarantee being **per task** rather than per space, so
+> it survives someone restoring chat fallback by deleting the pin, and (b) a
+> skip that is **distinguishable** in the ledger from any other error
+> (`last_status` is only `ok`/`error`). Owner's call at this checkpoint
+> whether that is worth doing now or after M3.2 makes it measurable.
+
+> **M2.2 deferred, not dropped (2026-08-21, [D-015](decisions.md)).** All 12 live
+> runs since the profile applied ran on `claude-opus-5`, so the checkpoint's "zero
+> posts from a non-primary leg" is already true by construction. Architecture stays
+> unfilled until M3.1 can measure whether a per-task guarantee earns its keep.
+
+**Checkpoint:** task #28 and its one-shots are gone; the first `feed-watch`
+one-shot produced either a sourced 1–3 line post or nothing; the 09:00 article
+trace carries `<feed_watch_digest … items="N">`; a week of spend is reported
+(target direction: well under ~$5.30/day — reported, not gated); zero group
+posts from a non-primary leg. **Added 2026-08-21 (audit):** `agent.trace_runs`
+is on; a factual chat question's trace shows the topic note being read and the
+next article appends to one; the football space runs with `persona.exclusive`
+and a member run's system prompt carries no preference-management paragraph; a
+swipe-reply follow-up sees the bot's own post from the previous evening; a
+"don't answer" message in `main` gets no reply.
+
+> **Extended 2026-08-21 ([D-016](decisions.md)–[D-018](decisions.md)).** The
+> 2026-08-21 audit (`docs/notes/football-audit-2026-08-21.md`) traced both
+> owner-reported failures — a hallucinated name and a joke refused as a
+> permission request — to mechanisms, not missing rules: the window, not a
+> memory; four personas, not one; no silent chat path. M2.3–M2.5 are those
+> mechanisms. Per the owner, nothing in them is tailored to the bot's state
+> today — M3.1/M4.1 are assumed to land; M2.3 is what gives M3.1's provenance
+> lint a source to check against. **Order:** M2.3 first (profile-side, no
+> restart); M2.4 and M2.5 are independent host stories and may run in
+> parallel with M3.1.
+>
+> **Build order note (2026-08-20, D-012):** M3.2 is being implemented before
+> M2.1. It has no dependencies, and an instrument installed after the change
+> it measures cannot show the before — feed-watch should ship against a
+> baseline the ledger already recorded. Milestone membership is unchanged.
+
+### Milestone 3: Proof of quality
+> The rules are testable without reading the chat.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M3.1 | Fixture harness: dated fixture items through the verify/article prompts in the private space + a deterministic output lint | football-reporter-fixture-harness | M1.1 | backlog |
+| M3.2 | Scheduled-run ledger: model, cost, outcome per run; dashboard badge + drawer, `mrctl tasks runs` | scheduled-run-ledger | — | done (2026-08-20, ahead of M2 — D-012) |
+
+**Checkpoint:** harness green on the fixture set (fresh item passes, undated
+and stale items dropped, emoji/HTML/line-count lint fires on seeded bad
+replies); every scheduled run of the last 48 h has a ledger row.
+
+### Milestone 4: Regression and monitoring
+> Every previously reported defect has a check that would catch its return;
+> a re-audit confirms; new problems surface from the ledger.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M4.1 | Regression suite for F1–F8 + `scripts/football-audit.ts` data dump + two-week re-audit note | football-regression-suite | M2.1, M3.1, M3.2 | blocked |
+
+**Checkpoint:** regression suite green in `bun run check`; re-audit note
+(`docs/notes/football-group-reaudit-<date>.md`) finds no recurrence of F1–F7
+and reports F8 spend; the ledger is the first place a new problem shows.
+
+## Bug track (parallel — not stories, per D-007)
+
+Filed at planning in `docs/bugs/`; fix with `/f-bug-fix` whenever convenient,
+independent of the milestones. Any *new* defect found while executing a story
+is filed the same way, never fixed inside the story.
+
+| Audit ref | Bug doc | Severity | Regression check lands in |
+|-----------|---------|----------|---------------------------|
+| F5 | `reply-to-member-triggers-bot.md` | moderate | M4.1 |
+| F7a | `chat-output-html-tags-not-stripped.md` | minor | M4.1 (lint also in M3.1) |
+| F7d | `responded-in-suffix-not-stored.md` | minor | M4.1 |
+| F7e | `bot-self-name-is-phone-in-reply-to.md` | minor | M4.1 |
+| — | `model-switch-disables-fallback.md` | moderate | M4.1 |
+| audit-2 C9 | `feed-watch-seen-ttl-not-refreshed.md` | moderate | M4.1 (fix **before** the feed-watch deploy) |
+| audit-2 C10 | `feed-watch-runas-non-user-principal.md` | moderate | M4.1 (fix **before** the feed-watch deploy) |
+
+The two `feed-watch-*` rows come from the 2026-08-21 audit's second pass
+(`docs/notes/football-audit-2026-08-21.md` §3.1): a `seen` TTL that counts
+from first sighting (a wave of stale items re-enters every 72 h) and a
+`runAs` that can be the literal string `dashboard` (phantom member row,
+member permissions). Both are small `watch.ts` changes with designed fixes
+in the bug docs; both gate the deploy.
+
+The last row is not from the 48h audit. It was found on 2026-08-20 while
+expanding the live `model.chain` from 2 legs to 5 (opus-5, sonnet-5,
+gemini-3.1-flash-lite, fable-5, haiku-4-5): `/model switch` truncates the chain
+to the chosen leg and no verb restores it.
+
+That same day the owner chose **Opus-only, no fallback, but all 5 switchable**,
+and this truncation is the only mechanism in the codebase that delivers it — so
+all 6 spaces are now deliberately pinned to `anthropic:claude-opus-5` and the
+chain serves purely as the `/model switch` menu. The bug is therefore half
+feature: what stays broken is that nothing can clear the pin, and that
+`/model list` still renders unreachable legs as if they were fallbacks. Any fix
+must be additive — see the bug doc before touching `resolveActiveIndex`.
+
+Bearing on the milestones: every run is now single-leg, so `max_retries_per_leg`
+is the only resilience left, and the M3.2 run ledger should record the model per
+run rather than assume the chain.
+
+Not bugs (handled by stories): F1 → resolved 2026-08-19, locked in by M1.1;
+F2 → M2.2; F3 → M1.2; F4 → M1.1 + M2.1 + M3.1; F6 → M1.1 honesty rule;
+F7c → M1.1 + M3.1 lint; F7f (Hebrew Telegraph slugs) → investigated in
+M1.2, likely accepted; F8 → M2.1 + M3.2.
+
+## Dependency Graph
+
+```
+M1.1 ─┬─► M1.2
+      ├─► M2.1 ─┐
+      ├─► M2.3 ─┤   (M3.1's provenance check reads M2.3's notebook — soft)
+      └─► M3.1 ─┼─► M4.1
+M2.2 (independent)   │
+M2.4 (independent) ──┤
+M2.5 (independent) ──┤
+M3.2 (independent) ──┘
+```
+
+M1.1 gates everything that touches the space's prompts. M2.2, M2.4, M2.5 and
+M3.2 are core changes with no football dependency and can run in parallel —
+M3.2 is worth starting early because its ledger is what makes the M2 and M4
+checkpoints measurable. M2.3 is profile-side and gates only the notebook half
+of M3.1's provenance check; the rest of M3.1 is unblocked.

package/docs/goals/whatsapp-bot-hardening/README.md

@@ -0,0 +1,43 @@
+# whatsapp-bot-hardening — start here
+
+Ops and planning docs for running Mercury as a live WhatsApp bot. Everything in
+this folder is documentation; nothing here is executed.
+
+## Where things are
+
+| Path | What |
+|------|------|
+| [`open-threads.md`](open-threads.md) | **Start here.** Everything still outstanding. |
+| [`roadmap.md`](roadmap.md) | What shipped, milestone by milestone |
+| [`decisions.md`](decisions.md) | D-001…D-014, with reasoning and revisit conditions |
+| [`goal.md`](goal.md) | Goal statement, constraints, success criteria |
+| [`archive/`](archive/) | Completed work — the 8 story specs, the setup plan, the bug-investigation handoff |
+
+## Archived — read for context, don't plan from them
+
+- `archive/handoff-2026-08-09.md` — the bug investigation. Every fix in it
+  shipped; the root-cause analysis is still the best map of *why*.
+- `archive/setup-plan-2026-08-06.md` — how the bot was built. Phases 0–5
+  complete; the Gemini and npm-install sections are superseded.
+- `archive/<story>.md` — one spec per hardening story, with retrospectives.
+
+Both archived files carry a header listing exactly what in them has gone stale.
+
+## Where the code lives
+
+Since 2026-08-10 there is **one** source of truth:
+
+| Tree | Role |
+|------|------|
+| `D:\Projects\mercury` (Windows) | **Source of truth.** All edits and commits happen here. Pushes to `origin` once contributor access lands. |
+| `~/mercury-src` (WSL) | Run-only mirror. The systemd unit `mercury` runs `bun` directly against this checkout — no build step. Never commit here. |
+| `~/whatsapp-bot` (WSL) | Runtime data only — config, `.env`, SQLite DB. The unit's working directory. |
+
+After changing code on Windows, push it to the running bot with:
+
+```bash
+wsl.exe -d Ubuntu -- bash -lc '~/sync-mercury.sh'
+```
+
+That fetches from the Windows clone, hard-resets the mirror to match, reinstalls
+dependencies only if `bun.lock` changed, and restarts the service.

package/docs/goals/whatsapp-bot-hardening/archive/ambient-group-context.md

@@ -0,0 +1,211 @@
+# Ambient Group Context
+
+**Status**: Done
+**Slug**: ambient-group-context
+**Goal**: whatsapp-bot-hardening
+**Milestone**: 2
+**Created**: 2026-08-09
+**Last updated**: 2026-08-09
+
+---
+
+## Goal
+
+> Part of goal [whatsapp-bot-hardening](../goals/whatsapp-bot-hardening/goal.md).
+> HANDOFF Bug 1 — highest impact.
+
+The bot cannot see any group message it isn't tagged in. `ambient.enabled`
+defaults to true and the ambient-write branch works as designed — but it lives
+in `runtime.ts:591-612` behind `processIngress`, which is only reached **after**
+the early return at `handler.ts:237-240` has already dropped untriggered
+messages. It is dead code: across the whole DB there are exactly 2 ambient rows,
+both stray `/`-prefixed messages that leaked through the `isCommand` bypass.
+Upstream has not fixed this (`handler.ts` byte-identical on origin/main).
+Depends on `message-author-attribution` (M2.1) so ambient rows carry authors
+from the start, and ships **only with** its own context cap + retention TTL
+(D-003).
+
+## User Stories
+
+- As a group member, I want to tag the bot and ask "what did we just decide?"
+  and have it answer from the conversation it silently observed.
+- As the operator, I want ambient storage bounded (context budget + TTL) so
+  every group message becoming a row doesn't starve real turns or grow the DB
+  forever.
+
+## MVP Scope
+
+**In scope:** public `recordAmbient(ingress)` on `MercuryCoreRuntime`
+(extracted from `runtime.ts:591-612`, guards intact); call it from the
+handler's early-return path; a dedicated bounded ambient context query; ambient
+retention TTL in `storage-cleanup.ts`.
+
+**Out of scope:** avoiding media downloads for untriggered messages —
+`bridge.normalize` already runs before the gate today (pre-existing cost, not
+added by this fix); tuning ambient *relevance* (which rows get injected) beyond
+a bounded recency window.
+
+---
+
+## Context for Claude
+
+- `src/core/handler.ts:237-240` — the early return that kills ambient; `ingress`
+  is already built at `:221`, so the data is in hand.
+- `src/core/runtime.ts:591-612` — the ambient-write branch to extract
+  (group-only + `ambient.enabled` + non-DM guards must survive the move).
+- `src/storage/db.ts:1047` (`getRecentTurns`) and `:1068` (`turnCount * 5`
+  window) — the budget ambient must NOT share.
+- `src/core/storage-cleanup.ts` — where the TTL goes.
+- `HANDOFF.md` Bug 1 — full analysis and evidence.
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+No new columns (`role='ambient'` rows already exist as a concept). New
+config surface:
+
+```yaml
+ambient:
+  context_rows: 30      # max ambient rows injected per turn (own query, own cap)
+  retention_days: 14    # TTL enforced by storage-cleanup
+```
+
+Defaults decided in code review; both must exist before the handler fix ships.
+
+### API Contracts
+
+None.
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `src/core/runtime.ts` | Modified | Extract `recordAmbient(ingress)` as a public method |
+| `src/core/handler.ts` | Modified | Call `core.recordAmbient(ingress)` before the early return |
+| `src/storage/db.ts` | Modified | Dedicated bounded ambient query (separate from `getRecentTurns`) |
+| `src/core/storage-cleanup.ts` | Modified | Ambient TTL |
+| test files alongside each | New/Modified | See tests below |
+
+### Implementation Sequence
+
+1. Extract `runtime.ts:591-612` into public `recordAmbient(ingress:
+   IngressMessage)`, preserving all guards (group-only, `ambient.enabled`,
+   non-DM). Pure refactor — behaviour identical.
+   - Read first: `src/core/runtime.ts:560-630`, `src/core/handler.ts:200-250`
+   - Verify: `bun run check` green; existing tests unchanged.
+2. Bounded ambient query in `db.ts` + wire the context builder to use it, so
+   ambient shares nothing with the `turnCount * 5` window.
+   - Read first: `src/storage/db.ts:1040-1080` and the context assembly that
+     consumes `getRecentTurns`
+   - Verify: unit test — ambient context returns ≤ N rows and user/assistant
+     turns are not displaced. **Blocker: step 3 must not ship without this.**
+3. Handler fix — replace the bare return at `handler.ts:240`:
+   ```ts
+   if (!shouldProcess && !isCommand) {
+     core.recordAmbient(ingress);
+     return;
+   }
+   ```
+   - Read first: `src/core/handler.ts:230-245`
+   - Verify: unit tests — writes for a group with `ambient.enabled`
+     unset/true; nothing for a DM; nothing when `ambient.enabled=false`;
+     called exactly once for a non-triggered group message and **not** for a
+     triggered one (no double-write).
+4. Retention TTL in `storage-cleanup.ts` for `role='ambient'` rows.
+   - Read first: `src/core/storage-cleanup.ts` (existing cleanup patterns)
+   - Verify: unit test — rows older than the TTL are removed, newer kept,
+     other roles untouched.
+
+---
+
+## Non-Negotiable Rules
+
+- The handler fix (step 3) never ships without the context cap (step 2) and
+  TTL (step 4) — D-003.
+- All existing guards survive the extraction: no ambient writes for DMs, none
+  when `ambient.enabled=false`.
+- No double-write for triggered messages.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| High-volume group floods ambient | Cap bounds the prompt; TTL bounds the DB; both configurable |
+| `/`-prefixed unknown command in a group | Still falls through to ambient (coordinated with M3.2's routing change) |
+| Triggered message | Processed normally, not also recorded ambient (regression test) |
+| Ambient rows crowd out real turns | Dedicated query — structurally impossible to share the turn budget |
+| Privacy: bot now stores all group chatter | TTL is the mitigation; called out in the PR (roadmap Completion §4) |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (commit `4bf5505`)
+- [x] `recordAmbient` extracted (step 1)
+- [x] Bounded ambient query (step 2)
+- [x] Handler fix (step 3)
+- [x] Retention TTL (step 4)
+- [x] 17 unit tests green; `bun run check` passes (1367 pass / 0 fail)
+- [x] Deployed and running
+- [ ] **Manual (needs a phone):** 3 untagged messages in a test group → 3 new
+      `role='ambient'` rows; tag the bot → it can recount them
+- [ ] **Verify with data** once the group sees traffic:
+      `SELECT space_id, role, COUNT(*) FROM messages GROUP BY space_id, role`
+      — ambient for `greece2026` must go above 0 and keep growing
+- [x] No secrets or `.env` files committed
+- [x] No unrelated files modified
+
+---
+
+## Open Questions
+
+- [x] Defaults shipped as proposed: `ambientContextRows: 30`,
+  `ambientTtlDays: 14`. Both are `mercury.yaml`/env-overridable
+  (`MERCURY_AMBIENT_CONTEXT_ROWS`, `MERCURY_AMBIENT_TTL_DAYS`) so they can be
+  tuned once real volume is observed, without a code change.
+
+---
+
+## Retrospective
+
+**Residual risks / follow-ups:**
+- Ambient volume in a busy family group is still unmeasured. The caps make it
+  safe, but the *right* numbers need a week of real data — revisit at the M2
+  checkpoint.
+- Media attached to untriggered messages is still downloaded and discarded
+  (`bridge.normalize` runs before the gate). Pre-existing, not worsened by
+  this change — accepted, as the spec states.
+
+**What changed from the plan:**
+- Config went into `AppConfig` (`ambientContextRows`, `ambientTtlDays`) rather
+  than the per-space config keys the spec sketched, to match how
+  `inboxTtlDays`/`outboxTtlDays` already feed `storage-cleanup`. `ambient.enabled`
+  stays per-space as it was.
+- Ambient cleanup runs **before** the spaces-directory scan. That scan
+  early-returns when the directory is unreadable, which would have silently
+  disabled retention on exactly the hosts most likely to need it.
+
+**Key decisions made during implementation:**
+- `getRecentTurns` now excludes ambient outright rather than merely fetching
+  more rows. Padding the LIMIT would have made starvation less likely but
+  still possible; two queries make it structurally impossible.
+- The handler and `handleRawInput` paths are mutually exclusive by
+  construction (one returns before the other can run), which is what makes
+  "no double-write" a property rather than a check. A test pins it.
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] New inter-package interaction (handler → runtime.recordAmbient)

package/docs/goals/whatsapp-bot-hardening/archive/command-routing-consistency.md

@@ -0,0 +1,210 @@
+# Command Routing Consistency
+
+**Status**: Done
+**Slug**: command-routing-consistency
+**Goal**: whatsapp-bot-hardening
+**Milestone**: 3
+**Created**: 2026-08-09
+**Last updated**: 2026-08-09
+
+---
+
+## Goal
+
+> Part of goal [whatsapp-bot-hardening](../goals/whatsapp-bot-hardening/goal.md).
+> HANDOFF Bugs 6b, 6d, 6e + redundancy cleanup — the rest of the command-surface
+> audit after the destructive trio (M3.1).
+
+Three consistency defects remain: (1) slash commands in groups are silently
+ignored unless the trigger word is present — `routeInput` re-applies the
+trigger gate that `handler.ts`'s `isCommand` bypass was meant to skip, so the
+bypass accomplishes nothing except filing commands as ambient chat (this is
+exactly how the two stranded baduk commands ended up in the DB); (2) chat and
+CLI permission gates disagree — a promoted space admin denied `/spaces delete`
+in chat can still destroy the current space via `mrctl`; (3) small argument/help
+defects: `/resume <arg>` silently ignores its argument, `/help pause` returns
+"No help available". Plus the audited redundancy cleanup (D-009).
+
+## User Stories
+
+- As a group member, I want a bare `/spaces list` to work without tagging the
+  bot, because that's what the `/` prefix visibly promises.
+- As the operator, I want chat and CLI to enforce the *same* permission answer
+  for the same action, so the tighter gate can't be bypassed.
+- As any user, I want `/resume 5m` to either work as written or error — not
+  silently do something else — and `/help pause` to actually document `/pause`.
+
+## MVP Scope
+
+**In scope:** trigger-free slash-command routing in groups (known commands
+only; unknown `/foo` still falls through to ambient — D-007); lift
+`spaces.delete` out of the blanket space-admin default grant so CLI matches
+chat's seeded-admin gate (D-008); `/resume` rejects unknown args; `verbs`
+metadata for `pause` incl. documenting the `^(\d+)(m|h)$` duration format; drop
+`/model active`; rewrite `/compact` vs `/clear` help to state the
+`session_boundary` vs `clear_boundary` difference (D-009).
+
+**Out of scope:** merging `/compact` and `/clear` — deliberately not done blind
+(D-009); any change to member default permissions (already minimal and correct).
+
+---
+
+## Context for Claude
+
+- `src/core/router.ts:105-115` — `matchTrigger` returns `ignore` before the
+  slash parse; the ordering to fix.
+- `src/core/handler.ts:236-240` — the `isCommand` bypass that currently
+  accomplishes nothing (coordinate with M2.2's `recordAmbient` call there).
+- `src/core/router.ts:33` (`SEEDED_ADMIN_COMMANDS`) and
+  `src/core/permissions.ts:208-210` (blanket admin grant), `:192-197`
+  (member defaults — untouched).
+- `src/core/commands.ts` — `SLASH_COMMANDS` (resume verbs, pause `verbs`
+  array, `/model active` removal, compact/clear descriptions);
+  `parsePauseDuration`.
+- `HANDOFF.md` Bug 6 — full audit incl. the redundancy verdicts table.
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+None.
+
+### API Contracts
+
+Permission semantics change: `spaces.delete` is no longer granted by default
+space-admin role — only the seeded admin (config) passes `checkPerm` for it.
+This is a **tightening**; document it in the PR behaviour-change list.
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `src/core/router.ts` | Modified | Parse known slash commands before/despite the trigger gate in groups |
+| `src/core/permissions.ts` | Modified | Lift `spaces.delete` from the blanket admin grant |
+| `src/core/commands.ts` | Modified | `/resume` arg rejection; `pause` verbs + duration docs; drop `/model active`; honest compact/clear help |
+| test files alongside each | New/Modified | See tests below |
+
+### Implementation Sequence
+
+1. **Trigger-free slash routing in groups** — in `routeInput`, recognize a
+   known slash command before the trigger `ignore`; unknown `/foo` keeps
+   falling through (to ambient once M2.2 lands). Coordinate with the
+   `handler.ts` bypass so there's exactly one gate.
+   - Read first: `src/core/router.ts:100-120`, `src/core/handler.ts:230-245`,
+     M2.2's spec (shared code path)
+   - Verify: unit — bare `/spaces list` in a group resolves as a command;
+     unknown `/foo` in a group does **not** become a command.
+2. **Permission alignment** — remove `spaces.delete` from
+   `getDefaultPermissions`' admin set; confirm the seeded-admin path still
+   passes everywhere it should.
+   - Read first: `src/core/permissions.ts:185-215`, `src/core/router.ts:30-35`
+   - Verify: unit — a promoted (non-seeded) space admin gets the same denial
+     from the chat path and the CLI/API path.
+3. **`/resume` argument handling** — pass `verb` through; unknown/unsupported
+   args error with usage instead of silently acting as bare `/resume`.
+   - Read first: `src/core/commands.ts` (`executeResumeCommand` and its caller)
+   - Verify: unit — `/resume extra` errors; bare `/resume` unchanged.
+4. **`/help pause`** — add the `verbs` array so `formatCategoryHelp` works;
+   document the accepted duration format (`\d+m|\d+h`).
+   - Read first: `src/core/commands.ts:55-67`, `formatCategoryHelp`,
+     `parsePauseDuration`
+   - Verify: unit — `/help pause` returns real help text.
+5. **Redundancy cleanup** — remove `/model active` (the fact lives in
+   `/model list`'s `← active` marker); rewrite `/compact` and `/clear`
+   descriptions to state the actual boundary difference (`db.ts:913` vs `:936`).
+   - Read first: `src/core/commands.ts` model/compact/clear entries,
+     `src/storage/db.ts:905-940`
+   - Verify: unit/help-snapshot — `/model active` gone from help and routing;
+     new descriptions render.
+
+Step 1 should land after M3.1's step 4 (same router file, `/`-handling).
+
+---
+
+## Non-Negotiable Rules
+
+- Unknown `/foo` in a group must never execute as a command — it falls through
+  (ambient), preserving the safe default.
+- Member default permissions are not touched.
+- Every user-visible behaviour change here goes in the PR's explicit
+  behaviour-change list (roadmap Completion §6).
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Message that merely *starts* with `/` but isn't a command (`/shrug`) | Not in `SLASH_COMMANDS` → falls through to ambient, never executes |
+| DM slash commands | Unchanged — DMs never required the trigger |
+| Seeded admin also holds space-admin role | Passes both gates before and after — no regression |
+| Muscle memory: users who typed `Wiz /spaces list` | Still works — trigger + command remains valid |
+| `/model active` users | Removal listed in PR behaviour changes; `/model list` shows the same fact |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (commit `4f05fbb`)
+- [x] Trigger-free slash routing (step 1)
+- [x] Permission alignment (step 2) — via a route-level check, see retrospective
+- [x] `/resume` args (step 3)
+- [x] `/help pause` (step 4)
+- [x] Redundancy cleanup (step 5)
+- [x] 11 unit tests green; `bun run check` passes (1404 pass / 0 fail)
+- [ ] **Manual (needs a phone):** bare `/spaces list` untagged in a test group
+- [x] No secrets or `.env` files committed
+- [x] No unrelated files modified
+
+---
+
+## Open Questions
+
+- [x] none
+
+---
+
+## Retrospective
+
+**Residual risks / follow-ups:**
+- With no seeded admins configured, `spaces.delete` keeps its old behaviour
+  (any space admin passes). Deliberate — the alternative is a deployment where
+  nobody can delete a space — but it means the alignment only bites where
+  `permissions.admins` is set. Accepted.
+
+**What changed from the plan:**
+- **D-008 was not implementable as written.** The plan said to lift
+  `spaces.delete` out of the blanket admin grant. But seeded admins are
+  *seeded into the database as role `admin`* (`resolveRole` →
+  `db.seedAdmins`), so seeded and promoted admins are indistinguishable by
+  role — removing the permission from `admin` would have locked out everyone,
+  including the person the chat gate is designed to admit. The alignment
+  instead lives in the delete route, which now asks the same seeded-admin
+  question the chat path asks. Same outcome, and it does not depend on a role
+  distinction that does not exist.
+
+**Key decisions made during implementation:**
+- Slash-command admission is by *known command name*, not by the `/` prefix:
+  `namesKnownCommand()` checks `SLASH_COMMANDS` and `CHAT_COMMANDS`, so
+  `/shrug` still falls through to ambient. This keeps the safe default while
+  making the handler's long-dead `isCommand` bypass finally mean something.
+- `/model active` kept as a redirect rather than deleted outright, so muscle
+  memory lands on an explanation instead of "unknown verb".
+- `/compact` and `/clear` were not merged. Their real difference was verified
+  in the code first (`min_message_id` is permanent, `clear_boundary` is reset
+  after each read) and then written into the help text, which is what the
+  audit actually asked for.
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] none expected