mercury-agent 0.24.1 → 0.24.2-beta.0

package/docs/extensions.md

@@ -174,6 +174,7 @@ Both `workspace_init` and `before_container` events include:
 
 `before_container` also includes:
 - `attachments` — incoming `MessageAttachment[]` (e.g. voice, images), if any
+- `ambientAttachments` — files overheard in this conversation since the bot last ran in it (a group voice note sent without a mention), each with `authorId` / `authorName`. Only authors whose role holds `media.receive`, only files still on disk, at most 10 rows, never on scheduled runs. Handed over once: the run saves its user turn, and the next run looks only past it — including when the handler failed, so a failed transcription is not retried.
 
 #### `before_container` mutations
 

package/docs/goals/conversation-review/decisions.md

@@ -0,0 +1,352 @@
+# Decisions: Conversation Review
+
+**Goal**: [conversation-review](goal.md)
+
+## D-001: The scan is a host-side Mercury extension, `conversation-review`, running on each bot
+- **Category:** architecture
+- **Decided:**
+  - New directory `examples/extensions/conversation-review/`, host-side only. It
+    has no CLI, no skill, no permission and adds nothing to the agent image.
+  - It borrows two existing patterns:
+    - from **napkin**: `mercury.job` scheduling, a throttle kept in
+      `mercury.store`, and a read-only `bun:sqlite` open of `state.db`;
+    - from **longview**: a `pi` spawn with no tools.
+  - Both bots run the same code. The local bot gets it from the installed
+    snapshot. Tagula gets it through the release.
+- **Alternatives considered:**
+  - **A laptop-side scanner that pulls `state.db` from both boxes.** Raw client
+    conversations would leave Hetzner, and the Tagula runbooks already exclude
+    `state.db` from backups for exactly that reason.
+  - **A scheduled agent task** (a `tasks` row with a review prompt). The agent
+    would then read other spaces' messages from inside a container, which needs
+    cross-space read authority that does not exist until `space-links`. Its
+    output also becomes a chat message, not a file.
+  - **Core code in `src/`.** Every deployment would pay for it. An extension can
+    be off by default.
+- **Reasoning:** Data stays where it lives, one code path serves both bots, and
+  napkin already proves the shape: an hourly job, a read-only DB and a pi spawn
+  on the owner's subscription.
+- **Revisit if:** `space-links` ships a management space with cross-space read on
+  Tagula. The weekly deep pass could then run as a management-space task that
+  can take follow-up questions.
+- **Used by:** all stories.
+
+## D-002: A shared identifier redactor with a fail-closed gate, in core
+- **Category:** pattern
+- **Decided:**
+  - `src/core/redact-identifiers.ts` exports `redactIdentifiers(text, known)` and
+    `assertNoIdentifiers(text)`.
+  - It replaces:
+    - phone numbers (international and Israeli local forms)
+    - WhatsApp JIDs and LIDs (`…@s.whatsapp.net`, `…@lid`, `…@g.us`)
+    - e-mail addresses
+    - every `author_name` and `display_name` the scan saw in the window, and
+      `space_roles.display_name`
+  - Each replacement is a stable per-report tag (`[member-3]`, `[phone-1]`), so
+    one person reads consistently within a report. Authors become their role.
+  - The gate runs on the final assembled report string and throws if any
+    identifier survives. The report is then not written, and the DM says why.
+- **Alternatives considered:**
+  - **Redact per field.** CLAUDE.md warns against exactly this: each field fixed
+    in turn, and the next one missed.
+  - **Paraphrase only.** Rejected by the owner, 2026-09-28. Evidence is what
+    makes a finding actionable.
+  - **Reuse `redactTokens`.** It covers secrets, not people.
+- **Reasoning:** "Prefer one pass at the join." The gate on the final string
+  cannot miss a site. Phone numbers also appear inside message bodies, not just
+  in columns (Tagula INBOX thread, 2026-08-28), so a column-level redactor is not
+  enough. It lives in core because `secret-redaction-at-ingress` and
+  `mercury-triage` will want the same function.
+- **Revisit if:** a report needs a real identifier to be actionable (for example
+  "this member's LID never resolves"). The fix is a local lookup table beside the
+  report on the box, never an identifier in the committed file.
+- **Used by:** redact-identifiers-with-gate, conversation-review-report-and-digest,
+  review-intake-to-repo.
+
+## D-003: The daily judge runs on a cheap model on the chain's provider; the weekly pass runs on the strong leg
+- **Category:** trade-off
+- **Decided:**
+  - **Daily.** The daily judge spawns pi on the provider of the space's
+    resolved leg (`resolveSpaceModelLeg`), the same one it would use anyway,
+    with an explicit model from `conversation-review.judge_model`. The default is
+    the cheap tier (`claude-haiku-4-5`). Credentials come from the leg's provider,
+    exactly as longview gets them.
+  - **Weekly.** The weekly synthesis runs on the space's resolved leg unchanged,
+    which is the strong tier.
+  - Both spawns get a row in `tests/inventories/pi-spawns.ts`. The row records
+    the explicit model override and its reason.
+- **Alternatives considered:**
+  - **The strong leg for every daily exchange.** At the owner's volume that is
+    Opus on every exchange every day, which is the cost shape
+    `feed-watch-triaged-roundup` exists to remove.
+  - **A heuristic pre-filter.** Rejected by the owner: the judge reads every
+    exchange.
+- **Reasoning:** The 2026-09-07 owner decision for the `explore` subagent set the
+  precedent: a cheap tier as an explicit `provider` + `model` pair on the same
+  subscription. The house rule forbids pi's default preamble and a foreign
+  credential. It does not forbid a cheaper model on the same provider.
+- **Revisit if:** the weekly spot check (D-006) finds that the cheap judge misses
+  real problems at a rate the owner won't accept. Then raise
+  `judge_model`, which is a config change.
+- **Used by:** conversation-review-daily-judge,
+  conversation-review-weekly-synthesis.
+
+## D-004: The unit of judgement is the exchange: user turns, then the bot's reply, plus context before them
+- **Category:** architecture
+- **Decided:**
+  - An **exchange** is one or more consecutive `role='user'` rows in one
+    `conversation`, followed by the `role='assistant'` rows up to the next user
+    turn.
+  - The judge also sees up to N earlier rows as context. The default is 6,
+    capped by characters.
+  - Rows with `source='scheduler'` (task output) are judged as **task
+    exchanges**, where the prompt is the task, not a user.
+  - `ambient` rows are context only, never judged.
+  - `tool` rows are dropped.
+  - Exchanges are **batched per conversation** into one judge spawn, up to a
+    character budget, so a space with 40 exchanges costs a few spawns rather than
+    40.
+- **Alternatives considered:**
+  - **Whole-day conversation per spawn.** It overflows the argv cap
+    (`MAX_ARG_STRLEN`) and the judge loses precision.
+  - **One spawn per exchange.** Cost and wall clock scale with volume.
+- **Reasoning:** The 48 h audit cited findings as message `#ids` inside
+  exchanges. Batching keeps cost linear in text size, not in message count.
+- **Revisit if:** trace linking lands (`trace-records-system-prompt`, M4). The
+  unit could then include the run's tool calls.
+- **Used by:** review-exchange-reader, conversation-review-daily-judge.
+
+## D-005: The finding is a fixed JSON schema; the report is Markdown rendered from it
+- **Category:** pattern
+- **Decided:**
+  - The judge returns JSON: `{findings: Finding[]}`. The host validates it and
+    drops anything invalid, counting and reporting the drops.
+  - `Finding` fields:
+    - `kind`: `bug | feature | profile | config`
+    - `scope`: `global | space`
+    - `target_layer`: one of the named layers in `docs/behavior-layers.md` §3, a
+      closed enum copied into the prompt
+    - `severity`: `high | moderate | minor`
+    - `confidence`: 0–1
+    - `message_ids`: must exist in the batch; the host checks this
+    - `what_went_wrong`
+    - `proposed_improvement`
+    - `fingerprint`: normalized kind + target_layer + a short slug, used to find
+      duplicates across days
+  - The host renders `report.md` and writes `report.json` beside it. Intake reads
+    the JSON.
+- **Alternatives considered:**
+  - **Free-text reports.** Nothing can be deduplicated or promoted in one step.
+- **Reasoning:** The finding already had this shape in the 72 h review. The
+  closed layer enum is what makes "global or space-specific" something the host
+  checks, not prose.
+- **Revisit if:** the layer set in `behavior-layers.md` §3 changes. The enum is
+  pinned by a test against that file (one contract, one statement).
+- **Used by:** conversation-review-daily-judge,
+  conversation-review-report-and-digest, review-intake-to-repo,
+  conversation-review-weekly-synthesis.
+
+## D-006: The weekly pass synthesizes the daily findings and spot-checks unflagged exchanges
+- **Category:** scope
+- **Decided:**
+  - The weekly job reads the last 7 daily `report.json` files, not the raw week.
+  - It clusters findings by fingerprint and meaning across spaces, and promotes
+    recurring space-level findings to global candidates.
+  - It re-judges a random sample of exchanges the daily judge passed, on the
+    strong leg. The default sample is 20 per bot.
+  - It reports the miss rate as the daily judge's measured recall.
+- **Alternatives considered:**
+  - **A strong-model re-read of the whole week.** It duplicates the daily cost
+    at Opus prices.
+- **Reasoning:** Synthesis is where "global vs space" becomes visible. The same
+  failure seen in three spaces is a code or global-profile finding, not three
+  `AGENTS.md` lines. The spot check turns "the cheap judge is good enough" into a
+  number that is re-measured every week.
+- **Revisit if:** recall stays near 100% for a month. Shrink the sample.
+- **Used by:** conversation-review-weekly-synthesis.
+
+## D-007: Reports reach the repo by a pull on this machine, run by the owner (`/f-review-intake`)
+- **Category:** architecture
+- **Decided:**
+  - Each bot writes `<dataDir>/reviews/<YYYY-MM-DD>-{daily|weekly}/report.{md,json}`
+    and keeps 60 days.
+  - `scripts/review-intake.ts` on this machine:
+    1. reads the local bot's directory directly;
+    2. copies Tagula's over `ssh root@<box>` (`scp` of the reviews directory
+       only);
+    3. re-runs `assertNoIdentifiers` on every file;
+    4. writes `docs/reviews/<date>-<bot>-<kind>.md`;
+    5. emits an index of candidate docs and the ledger for triage (D-011).
+  - The `/f-review-intake` command wraps the script and triages every finding
+    against what is already documented or landed, then proposes an action per
+    finding for the owner to approve ([D-011](#d-011-intake-relates-every-finding-to-existing-work-before-deciding-what-to-do-with-it)).
+  - Nothing is committed or pushed automatically.
+- **Alternatives considered:**
+  - **The bot commits to the repo.** It would need a write-capable credential on
+    a client box, and it would race live sessions in the shared checkout
+    (CLAUDE.local.md: "staging in the shared checkout is a race").
+  - **Tagula's `/api/console/*` control plane.** It is authenticated with the box
+    secret and has no reviews route. Add a route only if SSH access goes away.
+- **Reasoning:** Human in the loop is the stated scope. The DM is the trigger,
+  and intake is where review happens. SSH to the box is already how operators
+  work there (tagula-agents runbooks).
+- **Revisit if:** detection is trusted enough to automate filing (a later goal).
+- **Used by:** review-intake-to-repo, conversation-review-on-tagula.
+
+## D-008: Scheduling is a cron with an explicit time zone, off by default, one `conversation-review.enabled` switch per bot
+- **Category:** pattern
+- **Decided:**
+  - The jobs are hourly `interval` ticks that check a due-time computed in
+    `conversation-review.timezone` (default `Asia/Jerusalem`). The defaults are
+    daily at 04:00 and weekly on Sunday at 05:00.
+  - The throttle is kept in `mercury.store`. Missed runs catch up once, never
+    several times.
+  - The extension is **off** until `enabled=true`. Spaces can be excluded with
+    `conversation-review.exclude` (per space).
+  - The owner DM target is `conversation-review.digest_to`, a caller id resolved
+    by `ctx.send`.
+- **Alternatives considered:**
+  - **`mercury.job({cron})`.** It is parsed with no time zone (`jobs.ts:114`),
+    so it runs in the host's local time, and the Hetzner box is probably UTC.
+- **Reasoning:** Napkin's interval + throttle shape already survives restarts and
+  missed ticks. A fixed hour in a named time zone reads the same on both boxes.
+- **Revisit if:** `mercury.job` gains a time zone.
+- **Used by:** conversation-review-daily-judge,
+  conversation-review-weekly-synthesis, conversation-review-on-tagula.
+
+## D-009: Client spaces on Tagula are opt-in per bot, and client consent is an open owner question
+- **Category:** scope
+- **Decided:**
+  - On Tagula, `enabled=true` covers the owner's own spaces.
+  - Client spaces are scanned only when `conversation-review.include_clients=true`,
+    set by the owner after the consent question is answered.
+  - The local bot has no client spaces.
+- **Alternatives considered:**
+  - **Scan everything from day one.** Nothing on disk records client consent to
+    AI review (tagula-agents survey, 2026-09-28).
+- **Reasoning:** Excerpts of client conversations are the owner's decision to
+  expose, even redacted. That decision should be made once, explicitly, not by
+  deploying a release.
+- **Open question (owner):** do the Tagula terms, or each client, need to allow
+  automated quality review of conversations before `include_clients` is turned
+  on?
+- **Used by:** conversation-review-on-tagula.
+
+## D-010: The daily judge is a screener; a finding is a hypothesis until intake verifies it
+- **Category:** trade-off
+- **Decided:** (owner question, 2026-09-28: "what if the weak model makes a
+  mistake?")
+  - Nothing the cheap judge says is acted on directly. Its finding is a
+    *hypothesis with evidence*; the verdict belongs to intake (D-011), which runs
+    on a strong model with the repo in hand, and to the owner.
+  - Every kind of judge mistake has a named catcher:
+
+    | Mistake | Caught by | When |
+    |---|---|---|
+    | Output that isn't valid JSON, or a missing or out-of-range field | The host validator drops it and counts the drop | Daily |
+    | Invented message ids | Checked against the batch; dropped as `badIds` | Daily |
+    | Misquoted or invented evidence | The excerpt is read from `state.db` by message id, never taken from the judge's text | Daily |
+    | Flags an answer that was actually fine | Intake re-judges the excerpt first. A rejection goes into the ledger, the same fingerprint is suppressed afterwards, and it becomes a counter-example (M3.2) | Intake |
+    | Wrong kind, layer, scope or proposed fix | Treated as a hint only. Intake re-derives the layer by reading the real layer: `behavior-layers.md`, the space's profile, the code | Intake |
+    | Misses a bad answer | The weekly strong-model spot check measures recall (D-006). If recall is low, raise `judge_model` (D-003) | Weekly |
+    | Obeys an instruction written inside a conversation | The judge has no tools. The conversation is framed in the prompt as quoted data. Output is schema-validated and length-capped, and intake treats finding text as untrusted | Daily and intake |
+    | Wrong ranking of the digest's top three | The digest labels findings *unverified*. The DM is a pointer, not a verdict | Daily |
+
+  - The judge prompt leans toward **recall**. A false positive costs one line of
+    triage, but a miss is invisible until the weekly spot check. Noise is bounded
+    by a per-batch findings cap instead.
+- **Alternatives considered:**
+  - **A strong-model second opinion on every finding before the report is
+    written.** This duplicates intake's check without intake's repo context:
+    it can't see whether the behaviour is a documented decision, already fixed,
+    or a known bug. It also adds strong-leg spend on the box every day.
+  - **A confidence threshold that drops low-confidence findings.** The cheap
+    model's confidence is not calibrated, so a threshold would hide misses
+    rather than remove noise. Confidence is shown in the report and used only
+    for ordering.
+- **Reasoning:** Evidence that comes from the DB can't be wrong the way a claim
+  can. Classification is cheap to re-derive when you have the repo. Recall is
+  the only error that no reader downstream can see, so recall is the one that
+  gets a scheduled measurement.
+- **Revisit if:** precision measured at intake (M3.2) stays below about 50% for
+  two weeks. The owner's triage time is then the cost to cut, so tighten the
+  prompt or add counter-examples before anything else.
+- **Used by:** conversation-review-daily-judge,
+  conversation-review-report-and-digest, review-intake-to-repo,
+  conversation-review-weekly-synthesis, review-verdict-feedback.
+
+## D-011: Intake relates every finding to existing work before deciding what to do with it
+- **Category:** architecture
+- **Decided:** (owner, 2026-09-28)
+  - `/f-review-intake` never files a finding as new work straight from the
+    report. Each finding goes through three steps, in this order:
+    1. **Verify.** Re-read the redacted excerpt and decide whether the answer
+       really was poor. If it wasn't, the action is `reject` and steps 2 and 3
+       are skipped.
+    2. **Relate.** Search everything already documented or landed, and cite each
+       related item by path:
+       - open work: `docs/ideas/`, `docs/backlog/`, `docs/in-progress/`,
+         `docs/bugs/`, goal roadmaps' stories, `docs/refactor/`;
+       - landed work: `docs/archive/` and `docs/debug/**` post-mortems, including
+         their Residuals sections, plus `git log` for the area;
+       - decisions: goal `decisions.md` files, owner decisions in `CLAUDE.md` and
+         `CLAUDE.local.md`, and documented out-of-scope or residual lines;
+       - earlier reviews: the ledger `docs/reviews/ledger.json`;
+       - pending checks: `docs/pending-verification.md`.
+    3. **Decide.** Assess whether the finding is worth working on, then pick
+       exactly one action from a closed set:
+
+    | Action | When | What intake does after the owner approves |
+    |---|---|---|
+    | `reject` | The answer was fine (a judge error), or the problem is real but not worth the cost | Ledger entry with the reason. The fingerprint is suppressed |
+    | `known-limitation` | It matches a documented decision, out-of-scope line or accepted residual | Ledger entry linking that line. If the new evidence changes that decision's cost, the action becomes `needs-owner` instead |
+    | `duplicate` | The ledger already holds the same finding | Increment the seen count, then follow the earlier decision. A finding rejected earlier stays suppressed unless the evidence is new |
+    | `attach` | An open item already covers it: an idea, backlog or in-progress item, a bug, or a goal story | Append an "Evidence from conversation review" entry to that doc. The recurrence is priority signal |
+    | `fixed-not-deployed` | A landed change covers it, but the bot that produced the report runs a version that doesn't contain it | Ledger entry. Add or confirm a MANUAL-VERIFY line to re-check after the next deploy of that bot |
+    | `revisit` | A landed change covers it, **and** the bot's running version contains it | A new bug that links the closed item: "the fix for X does not cover this case", or a regression. If it's unclear whether the fix is even active, add a MANUAL-VERIFY re-check instead |
+    | `new` | Nothing related exists | Prefill `/f-bug-report` or `/f-feature-idea`, or propose a profile or config edit plus a MANUAL-VERIFY line |
+    | `needs-owner` | It conflicts with an owner decision, touches consent or scope, or the value call is close | Nothing. It is listed for the owner |
+
+  - **Worth working on** is judged on these points, and each one appears in the
+    triage row:
+    - severity;
+    - recurrence: days, spaces, and both bots;
+    - who was affected (a paying client over an owner test space);
+    - breadth of impact on Mercury over a single personal space (owner priority
+      of 2026-09-22);
+    - the cost of the target layer (an `AGENTS.md` line versus a code change);
+    - fit with `docs/ROADMAP.md`.
+  - The skill proposes a triage table with one row per finding: verdict,
+    related items with paths, action, value note. The owner approves, edits or
+    overrides each row, and only then does the skill apply the approved actions.
+    Every decision, approved or overridden, lands in the ledger.
+  - The split of work:
+    - `scripts/review-intake.ts` is deterministic. It pulls, re-gates, writes
+      `docs/reviews/`, and emits an index of candidate documents (path, title,
+      stage, status) plus the ledger.
+    - Matching and judgement are done by the skill, because similarity by
+      meaning is not a grep.
+  - The ledger also records the aliases of each canonical fingerprint, because
+    the cheap judge will slug the same problem differently on different days.
+  - `revisit` needs the bot's running version: every report records it (M1.4).
+- **Alternatives considered:**
+  - **Exact-fingerprint dedupe only** (the original D-007 step 5). It misses the
+    same problem under a different slug, and it cannot tell that a finding is
+    evidence for an open idea, a known limitation, or a regression of a fix.
+  - **Letting the script auto-file `new` findings.** That breaks the
+    human-in-the-loop scope, and it is exactly where a judge's false positive
+    would turn into backlog noise.
+- **Reasoning:** The value of a finding depends on what already exists. The same
+  excerpt can be:
+  - noise, when it restates an accepted limitation;
+  - priority signal, as the third occurrence of an open idea;
+  - the most valuable kind of finding, when it shows that a landed fix doesn't
+    work.
+
+  Only a pass that has read the corpus can tell these apart, and the planning
+  docs are the corpus.
+- **Revisit if:** the ledger shows the owner accepting the proposed action over
+  about 90% of the time for a month. Automating `duplicate` and
+  `known-limitation` is then the next step, in a later goal.
+- **Used by:** review-intake-to-repo, review-verdict-feedback,
+  conversation-review-report-and-digest.

package/docs/goals/conversation-review/goal.md

@@ -0,0 +1,150 @@
+# Conversation Review
+
+**Status**: Active
+**Slug**: conversation-review
+**Created**: 2026-09-28
+**Last updated**: 2026-09-28
+
+---
+
+## Goal Statement
+
+Scan the conversation logs of every space on both of the owner's bots on a
+schedule. The two bots are the local live bot (`~/whatsapp-bot`, the owner's
+personal bot) and the Tagula bot on the Hetzner server (client spaces; see the
+`tagula-agents` repo). Each scan produces a report of **poor bot answers that
+could be significantly improved**, with a proposed kind of fix for each one:
+
+- a **bug** in Mercury code
+- a **feature** Mercury does not have yet
+- a **profile/character change**, such as an `AGENTS.md` line, a preference, a
+  task prompt or a skill
+
+Each finding also says whether the change is **global** or **specific to one
+space**.
+
+The end state is a system that keeps improving Mercury on its own. This goal
+automates only the **detection** step. A human still reviews every finding and
+still does every implementation. Later milestones add more sophisticated scan
+features.
+
+Owner's words (2026-09-28): *"the scan should detect poor answers by the bot
+that can be significantly improved either by some fix or by a new feature for
+mercury. can be either code modifications or profile/character modifications,
+global or space specific. the end goal is to have an automated system that keeps
+improving mercury. as mentioned, at this point in time I first want to automate
+the detection of such improvements - review and implementation will still
+require a human in the loop."*
+
+This automates the manual reviews already done by hand:
+
+- `docs/notes/football-group-48h-audit.md`: 128 rows read one by one, producing
+  findings F1–F8.
+- The 72 h log review of 2026-09-16. It left about ten `docs/ideas/*` files,
+  four `AGENTS.md` sentences applied live, and MANUAL-VERIFY lines, but no
+  single note of its own.
+
+The triage those reviews used becomes the report's schema:
+
+| Kind of finding | Where it goes |
+|---|---|
+| Bug | `docs/bugs/` |
+| Feature | `docs/ideas/` |
+| Profile change | a layer named from `docs/behavior-layers.md` §3 |
+
+## Constraints
+
+- **Detection only.** The scan never changes a profile or a config, never files
+  a doc and never opens a PR. It writes a report and sends a DM, nothing else.
+- **Raw conversations never leave their box.** The scan runs on each bot, next
+  to that bot's `state.db`. Only the redacted report crosses to this machine.
+- **Redaction is enforced, not just intended.** Before a report file is written:
+  - phone numbers, JIDs, LIDs, e-mail addresses and member names are replaced;
+  - authors appear only as `owner` / `admin` / `member` / `bot`;
+  - excerpts are capped in length.
+  
+  A gate aborts the write if any identifier survives. This follows the tagula-agents
+  `scripts/export-space-messages.ts` precedent.
+- **Client spaces:** a report may quote short excerpts with identifiers redacted
+  (owner, 2026-09-28). The client-consent question is open, see Open Questions
+  in [decisions.md](decisions.md) D-009.
+- **Subscription OAuth only.** No Anthropic API key is used
+  (`no-api-key-model-billing`).
+- **Every scan is bounded, and the bound can be read.** There is a cap on the
+  exchanges judged and on the wall clock per scan and per spawn. Anything skipped
+  is stated in the report, never dropped silently (CLAUDE.md: "a limit the actor
+  cannot read is a trap").
+- **Every pi spawn follows the house rule.** It uses `--system-prompt`, runs with
+  no tools, and has a row in `tests/inventories/pi-spawns.ts`.
+- **The bot is never disturbed.** The scan reads `state.db` read-only and never
+  through `Db`, because `Db` runs migrations. It never blocks the host thread.
+- **Tagula runs released Mercury.** The Hetzner box installs the `mercury-agent`
+  npm package and image and updates nightly to `:latest`. Code reaches it only
+  through a release, never through `~/sync-mercury.sh`.
+
+## Preferences
+
+- Findings land in two places (owner, 2026-09-28):
+  - a report file in the mercury repo, under `docs/reviews/`, shaped so that
+    `/f-bug-report`, `/f-feature-idea` or a profile edit can promote any finding
+    in one step (required);
+  - a WhatsApp DM digest to the owner, a short summary pointing at the report
+    (required).
+- An LLM judge reads **every** exchange. Heuristics are not used as a pre-filter
+  (owner, 2026-09-28) (required).
+- There are two scans (owner, 2026-09-28) (required):
+  - a **light daily** pass: a cheap-tier judge over the last 24 h;
+  - a **deep weekly** pass: strong-tier synthesis over the week's findings, plus
+    a spot check of exchanges the daily judge did not flag.
+- Intake checks each finding against what is already documented or landed, and
+  decides from that and from whether the finding is worth the work. The options
+  are:
+  - merge it into an open item;
+  - file it as new;
+  - revisit a closed item to check that it works;
+  - drop it.
+
+  (owner, 2026-09-28) (required → [D-011](decisions.md))
+- It is built as a Mercury extension, in the style of napkin and longview, so both
+  bots run the same code (you decide → [D-001](decisions.md)).
+
+## Target Users
+
+- **The owner, as reviewer.** They get a DM each day and read a report that lists
+  the improvements worth making, each with evidence and a suggested target layer.
+  They then promote, reject or ignore each finding. (inferred)
+- **Future Claude sessions, as implementers.** They read a promoted finding the
+  same way they read `/f-bug-report` or `/f-feature-idea` output. (inferred)
+
+## Success Criteria
+
+1. On each bot, a daily scan runs unattended. It writes a report covering every
+   space with user exchanges in the window, and sends the owner a DM digest.
+2. Every finding carries the following, and a report missing any field fails
+   validation:
+   - kind (bug / feature / profile / config)
+   - scope (global / space)
+   - the target layer from `behavior-layers.md` §3
+   - severity and confidence
+   - message ids
+   - a redacted excerpt
+   - what went wrong and the proposed improvement
+3. A committed report contains no phone number, JID, LID, e-mail address or member
+   name. This is proven by the redaction gate and by a test that plants each form.
+4. A seeded bad answer is flagged by the next daily scan in a test space on the
+   local bot. The weekly report lists recurring issues across spaces with their
+   frequency.
+5. One command (`/f-review-intake`) brings both bots' reports into
+   `docs/reviews/` and triages every finding before any of it becomes work
+   ([D-011](decisions.md)):
+   - it verifies the finding;
+   - it relates it to documented and landed items, citing paths;
+   - it proposes an action: reject, known limitation, duplicate, attach to an
+     open item, fixed but not deployed, revisit a landed item, new, or needs
+     owner;
+   - it applies only the actions the owner approves.
+6. A judge mistake never becomes work unreviewed ([D-010](decisions.md)):
+   - evidence is read from the DB, never from the judge's text;
+   - classification is re-derived at intake;
+   - rejected false positives are not re-raised;
+   - recall is measured weekly.

package/docs/goals/conversation-review/roadmap.md

@@ -0,0 +1,94 @@
+# Roadmap: Conversation Review
+
+**Goal**: [conversation-review](goal.md)
+**Last updated**: 2026-09-28
+
+## Milestones
+
+### Milestone 1: Daily judge on the local bot
+> On the local bot, a daily scan judges every exchange of the last 24 h and
+> writes a redacted report on the box. The owner gets a DM digest.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M1.1 | Read a window of exchanges per space from `state.db`, read-only | review-exchange-reader | — | backlog |
+| M1.2 | `redactIdentifiers` + fail-closed `assertNoIdentifiers` in core | redact-identifiers-with-gate | — | backlog |
+| M1.3 | `conversation-review` extension: daily job, batched no-tools judge, validated findings | conversation-review-daily-judge | M1.1 | blocked |
+| M1.4 | Report (`report.md` + `report.json`) on the box and the owner DM digest | conversation-review-report-and-digest | M1.2, M1.3 | blocked |
+
+**Checkpoint:** on the local bot, after deploying and enabling:
+
+1. In a test space, the owner provokes one bad answer: a question the bot answers
+   wrongly or refuses without reason. They trigger a scan with the extension's
+   run-now hook (or wait for 04:00).
+2. `~/whatsapp-bot/.../reviews/<date>-daily/report.md` exists and flags that
+   exchange with a kind, a scope, a target layer and the right message id.
+3. `grep -E` for a phone number, `@s.whatsapp.net`, `@lid` and the owner's name
+   in the report returns nothing.
+4. A DM arrives with the finding count, the top three findings and the report
+   path.
+5. The report's footer lists spaces and exchanges judged, anything skipped with
+   the reason, spawns, wall clock and cost. The journal shows the scan never
+   stalled a live reply.
+
+### Milestone 2: Both bots, into the repo
+> The Tagula bot runs the same scan on its release. `/f-review-intake` brings both
+> bots' reports into `docs/reviews/` and triages each finding against what is
+> already documented or landed before any of it becomes work (D-011).
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M2.1 | `scripts/review-intake.ts` + `/f-review-intake`: pull, re-gate, then verify → relate → decide per finding, owner approves, ledger | review-intake-to-repo | M1.4 | blocked |
+| M2.2 | Enable on Tagula: release, config, `include_clients` gate, tagula-agents runbook | conversation-review-on-tagula | M1.4 | blocked |
+
+**Checkpoint:** a daily report from each bot lands in `docs/reviews/`. The
+intake triage table then shows, each row citing the paths it matched:
+- at least one finding re-judged as fine and proposed as `reject`;
+- one proposed as `attach` to an existing open item;
+- one checked against a landed item, as `fixed-not-deployed` or `revisit`;
+- a finding raised again on a later day, under a different slug, reads
+  `duplicate` and follows the earlier decision.
+
+Only the rows the owner approved were applied, and every row is in
+`docs/reviews/ledger.json`.
+
+### Milestone 3: Weekly deep pass and a feedback loop
+> A weekly strong-model synthesis clusters recurring issues across spaces and
+> measures the daily judge's recall. The owner's verdicts on findings sharpen the
+> judge.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M3.1 | Weekly job: cluster 7 days of findings, space → global promotion, recall spot check | conversation-review-weekly-synthesis | M1.4 | blocked |
+| M3.2 | The M2.1 ledger feeds the judge: suppressed fingerprints and counter-examples from rejected findings go back to each bot; precision appears in the weekly report | review-verdict-feedback | M2.1, M3.1 | blocked |
+
+**Checkpoint:** the first weekly report lists at least one cluster that spans two
+or more spaces, and states the measured recall of the daily judge. After a week
+of intake verdicts, it also states precision, and a rejected false positive is
+not re-raised.
+
+### Future milestones (to be decomposed when M3 completes)
+- **Trace-aware analysis:** link a reply to its run trace (message id in the
+  trace name, the system prompt recorded) so a finding can cite the tool call
+  that failed. This builds on `trace-records-system-prompt`.
+- **Friction signals as extra evidence:** corrections, rephrasing, "you didn't
+  answer". Relates to `repeated-style-corrections-become-preferences`.
+- **Cross-bot clustering** at intake, and a view of trends over time.
+- **Proposal → rehearsal:** replay the flagged exchange against a proposed
+  profile change on the shadow bench (`rehearsal-bench`, `mercury smoke`) and
+  attach the before/after answer to the finding.
+- **Drafted fixes:** a finding becomes a pre-filled bug or idea doc, or a draft
+  `AGENTS.md` diff, still approved by a human.
+
+## Dependency Graph
+
+```
+M1.1 ─┐
+      ├→ M1.3 ─┐
+M1.2 ─┼────────┴→ M1.4 ─┬→ M2.1 ─┐
+      │                 ├→ M2.2  ├→ M3.2
+      │                 └→ M3.1 ─┘
+```
+
+M1.1 and M1.2 can run in parallel. M2.1, M2.2 and M3.1 can run in parallel once
+M1.4 lands.