mercury-agent 0.16.2 → 0.17.0

package/docs/profile-guide.md

@@ -3,8 +3,8 @@
 This is the how-to for turning Mercury into *a particular assistant*: a
 barber's booking line, a copywriter's studio assistant, a football reporter in
 a friends' group, a trial-tier business helper. It is written from the
-profiles that exist — the four in `tagula-agents/tagula-agent-profiles`
-(barber, lawyers, copywriter, trial) and the football reporter in this repo —
+profiles that exist — the five in `tagula-agents/tagula-agent-profiles`
+(barber, lawyers, copywriter, trial, investor) and the football reporter in this repo —
 and from what went wrong while building them. Where it states how Mercury
 behaves, that was verified against the code and the running agent image on
 2026-08-21; the pointers are there so you can re-verify.
@@ -44,7 +44,7 @@ image — not against the diff.
 | | Applicative profile (`mercury-profile.yaml`) | Space profile (`config.yaml`) |
 |---|---|---|
 | Scope | the whole deployment: every space, every DM auto-space | one space |
-| What it carries | global `AGENTS.md`, extensions (capabilities, CLIs, skills), **exhaustive `member_permissions`**, `profile_prompt`, required capabilities, env | the space `AGENTS.md`, task prompts by live id, extension config keys, preferences to delete, workspace files to remove |
+| What it carries | global `AGENTS.md`, extensions (capabilities, CLIs, skills), **exhaustive `member_permissions`**, `profile_prompt`, required capabilities, env | the space `AGENTS.md`, task prompts by live id, extension config keys (incl. `role.member.permissions`, `persona.exclusive`), preferences to delete, workspace files to remove, **workspace files to seed once** (`MEMORY.md`, episode notes, a napkin addendum) |
 | Applied with | `mercury profiles apply <dir>` (non-interactive) or `mercury setup --profile`; needs a restart, and an image rebuild if it adds CLIs | `bun scripts/space-profile.ts apply --project <dir> --profile <dir>`; no restart |
 | Verified with | `mercury doctor`, a DM from a non-admin number, the startup warning about excluded member permissions | `space-profile check` (exit 1 + diff on drift); runs on every `~/sync-mercury.sh` |
 | Loader | `src/core/profiles.ts` | `src/profile/space-profile.ts` |
@@ -134,9 +134,20 @@ reads top-down and the first sections frame the rest.
 ## Silence                              when to say nothing and how (NO_UPDATE, "אין חדש")
 ## Integrity about what was done        "I wrote it" only after a successful write; who can change what
 ## Dedupe / memory routine              which file to read before posting and append after
+## Privacy                              "you may see it, you may not keep it" — never a denial of what is visible
+## What this space does NOT do          one line each; the reader's expectations, closed explicitly
 ## Overrides of platform text           the explicit sentences (see 4.4)
 ```
 
+Two of those sections are easy to skip and expensive to skip. **Privacy** phrased
+as a denial makes the bot lie — the investor profile's line is the honest
+shape: *"you do see the recent messages and the senders' names — do not deny
+it and do not answer 'I have no information'; what is forbidden is to
+**retain** it"* (no names in memory, notes or ledger). **What this space does
+not do** closes the door the persona leaves open: no portfolio, no scheduled
+posts, no legal advice, "you cannot send a message on your own initiative" —
+each one a promise the bot would otherwise make.
+
 Write in the language the bot speaks. Keep every rule **testable from the
 transcript** ("never more than 3 time slots in one message") rather than
 aspirational ("be helpful").
@@ -154,6 +165,14 @@ Compare:
 The second names the tool, the trigger, the reason, and the edge case
 (volunteering). That is what survives contact with a model under pressure.
 
+**Attach the failure mode, especially when it is invisible.** The most
+consistent habit across the tagula profiles is a clause after the rule saying
+what goes wrong and why nobody would notice: *"an invented date poisons the
+ledger silently — the record looks perfectly fine, only its score is wrong"*;
+*"no error, the skill just never fires"*; *"the file still looks right"*. A
+model told *why* a shortcut is dangerous takes it less often than one told
+not to; and the sentence doubles as the test case for the fixture harness.
+
 ### 4.3 The no-clock rule (every profile needs one)
 
 The model has a `Current date` line (UTC) and a shell; it has no reliable
@@ -191,10 +210,17 @@ win by being specific:
   default global `AGENTS.md` — a reporter that must give a full factual
   answer, or a bot that must not ask before acting, says so.
 
-Until [`one-voice-per-space`](backlog/one-voice-per-space.md) lands, also
-check the **global** `AGENTS.md` of the deployment: a space profile does not
-replace it, and `mercury init`'s template says "helpful AI assistant… ask
-before acting".
+Two of the four voices can be removed instead of out-argued. A space that owns
+its whole standard sets `persona.exclusive: "true"` in `extension_config`
+(shipped 2026-08-25, `behavior-layers.md` §1): the host then leaves the
+owner's global Bot Character out of the prompt and does not mount the global
+`AGENTS.md` (`mercury init`'s "helpful AI assistant… ask before acting") for
+that space. The platform paragraphs above still arrive and still need their
+override sentences; and the two capability paragraphs ("set a preference",
+"warn then mute") are already left out for a caller whose permissions cannot
+use them, so a member without `prefs.set` is no longer told to ask the admin.
+Removing a voice beats ranking it — precedence is a coin flip
+(`whatsapp-bot-hardening` A-3) and a fifth voice does not fix four.
 
 ### 4.5 Contradictions inside the file
 
@@ -215,6 +241,13 @@ failure turned into a rule with the exact wording to use. That is how a
 profile improves: a fixture fails → one sentence in the file → the fixture
 passes. Keep the sentences, drop the narrative.
 
+Date the rules that came from a decision — the investor skill writes
+*"Actionable, not flattering (est. 2026-08-11)"* and *"Horizons (approved
+2026-08-22)"* in the headings. A dated rule can be revisited; an undated one
+is argued from memory. The football profile keeps the dates in
+`decisions.md` instead (every `D-0NN` names the day and its `Revisit if:`),
+which works as long as the file's section names match the decision ids.
+
 ---
 
 ## 5. Accuracy: put the computation in code
@@ -257,6 +290,17 @@ And the honest fallback, in the global character and every profile: *"If you
 are not sure, say so instead of guessing. Never say you searched, read or
 changed anything unless you just ran the tool that does it."*
 
+**Make the bot measurable, not just fluent.** A profile that issues
+judgements — verdicts, predictions, "official / here-we-go / rumour" grades —
+records each one as an append-only row with a horizon and a due date, and
+re-analysis writes a *new* row that `supersedes` the old, never an edit. The
+investor profile does it with a tracker (`skills/stock-analysis/SKILL.md` §8:
+one `add` per verdict, a 14-day duplicate rule, "never record who asked");
+the football reporter does it with the notebook's `## Current State` /
+`## History` split plus the host's `task_runs` ledger. Either way the bot's
+own claims become something a script can grade a month later, which is what
+turns "the bot was wrong about X" from an anecdote into a rate.
+
 ---
 
 ## 6. Memory: design it, do not hope for it
@@ -296,12 +340,15 @@ What that means for a profile:
    in the engine. "The tracker is the source of truth — never answer 'what is
    the status?' from memory."
 6. **Size the history window to the space.** `context.mode` defaults to
-   `clear` for a hand-created space; `context.window_size` counts user turns
-   and scheduled runs are user turns. A space with several scheduled runs a
-   day loses its own chat within hours — which is how the football bot
-   contradicted its own lineup. Until `chat-window-and-silence` (M2.5)
-   excludes scheduler rows, size the window for the scheduled volume, and
-   never rely on the window for anything older than the current exchange.
+   `clear` for a hand-created space; `context.window_size` counts turns of
+   *conversation* — a person's message (reply included), or one of the bot's
+   own scheduled posts. Since `chat-window-and-silence` (M2.5) a scheduled
+   run's prompt is not in the window at all, so procedure can no longer crowd
+   out chat — which is how the football bot once contradicted its own lineup.
+   The bot's scheduled *posts* still hold a slot each, so a space that mostly
+   publishes still fills its window with its own articles: size the window
+   for how far back a follow-up should reach, and rely on the notebook, not
+   the window, for facts.
 
 ---
 
@@ -319,6 +366,24 @@ rules are:
 - When the host can do the work, prefer a **marker the host expands**
   (`[feed-watch:digest]`) over a skill the model must remember to run.
 - Verify use with a trace (`agent.trace_runs`), not with a correct answer.
+- **Formatting is a skill plus a lint, sharing one rule list.** The investor
+  profile moves every platform-rendering rule out of `AGENTS.md` into
+  `skills/whatsapp-formatting/SKILL.md` — "load this before composing *any*
+  message; not optional" — and keeps a one-line digest in `AGENTS.md` so the
+  rule survives an unread file. The skill is **grounded in the send
+  pipeline** and says so: Mercury's `applyRtlDirection` (`src/text/rtl.ts`)
+  strips leading bidi marks and prepends its own RLM per line, so a skill
+  telling the model to add RLE/RLM is telling it to do work the host
+  discards; the rule that remains is "start every line with a Hebrew word or
+  an emoji, never a ticker or a number". Likewise `normalizeChatMarkdown`
+  (`src/text/markdown.ts`) rewrites `**` and headings at send — the DB row is
+  what the model wrote, not what WhatsApp showed. Before writing a formatting
+  rule, read those two files and state which rules the host already
+  enforces. The countable rules (line length, emoji policy, `(source, dd/mm)`
+  per item, no HTML, no `**`) live in exactly one list that both the skill's
+  "checklist before sending" and the output lint (§11) are generated from —
+  tagula has the skill and no lint; the football harness is the first lint,
+  and its spec must not drift from the `## פורמט` section it measures.
 
 ---
 
@@ -344,6 +409,23 @@ rules are:
   cron in the README; `check` reports a deleted row as drift.
 - Restarting the service kills in-flight runs and loses the retry — check
   the crons before a restart.
+- **A quiet run is not a cheap run.** Every scheduled run — a verify one-shot
+  that answers `NO_UPDATE`, a scan that finds nothing — assembles the same
+  prompt stack as chat and pays for it before it says a word: the space
+  `AGENTS.md` (17 KB for the football reporter), `MEMORY.md`, the injected
+  notes, the digest, plus whatever the notebook rule makes it read. Feed-watch
+  replaced five blind scans a day (~$3) with ~46 verify runs a day, 70 % of
+  them `no_update` at $0.25–0.75 each — **$14–20/day** for one space. Budget a
+  profile by *runs per day × cost per run* from the ledger after the first
+  day, and cap the number of runs (`max_per_hour`, `batch_minutes`, a tighter
+  `exclude`, quiet hours) before touching prompt length. A host-side
+  pre-filter that opens no container is the only run that is free.
+- **Model is per space and changes without a deploy.** `model.active` is a
+  space-config row the owner can flip from chat, and a profile tuned on one
+  model behaves differently on another — Sonnet narrates "Now sending the
+  chat reply." into the sent text where Opus did not. The ledger records the
+  model per run; read it before blaming the prompt, and re-run the fixtures
+  after a switch.
 
 ---
 
@@ -400,8 +482,37 @@ live `AGENTS.md` or a task row by hand — `check` calls it drift and the next
   tests/                      runbook + fixtures
 ```
 
-Lessons from four deployments of this shape:
-
+Lessons from five deployments of this shape (barber, lawyers, copywriter,
+trial, investor):
+
+- **Split every file by one question — *does the agent write this at
+  runtime?*** Profile-owned files (`AGENTS.md`, task prompts, skills,
+  preferences, config keys) are replaced on every install: shipping a newer
+  one *is* the upgrade. Agent-writable files (`MEMORY.md`, `knowledge/`, a
+  registry, a ledger) are seeded once and never clobbered — overwriting one
+  destroys data that exists nowhere else, and there is no flag that makes
+  that safe. In a space profile the line is `agents_md`/`tasks`/
+  `extension_config` versus `workspace_seed`; `check` reports a changed
+  profile-owned file as drift and a changed seed as the feature working.
+- **Ledgers and databases never ship.** A profile creates them empty at
+  install and a gate fails on any committed `*.db` — that is the exact
+  mechanism by which one client's records would be installed into another
+  client's space. Paths the runtime creates (`outbox/`, `trackers/`) are
+  declared per profile (`runtime-paths.txt`) so the "every referenced path
+  exists" check can exempt them *and print the exemption count*.
+- **A profile installed into several spaces authors owner-dependent prose
+  twice**, in `<!-- OWNER:BEGIN -->…<!-- NOOWNER:BEGIN -->…` blocks, and the
+  installer deletes the losing block — never substitutes an empty string into
+  a sentence that then reads as a bug. A gate checks the blocks balance,
+  scanning only the file set the installer rewrites.
+- **Stage, verify, then write.** The investor installer builds the whole tree
+  in a temp dir, asserts no placeholder and no marker survives and every
+  absolute `/spaces/<id>/…` path it names exists in the stage, and only then
+  touches the live space — a failure leaves the space untouched rather than
+  half-installed. It also reads the last `messages` row from `state.db` and
+  refuses to overwrite while a turn is open: the space is mounted per run, so
+  a mid-turn write lands half the old persona and half the new one on a
+  request already executing, and nothing reports it.
 - **Typecheck the extension against the deployed layout, not the source
   tree.** Mercury copies only the extension dir; a deep relative import into
   a sibling engine compiles locally and fails on the box. tagula's
@@ -428,12 +539,35 @@ Lessons from four deployments of this shape:
    runbook and `test-full.sh`; the football goal has
    `football-reporter-fixture-harness` planned. Probe callers must be
    dedicated — probes spend the same per-caller daily budget as the test.
+1b. **Two tiers, named as such.** The deterministic tier (engine unit tests,
+   the output lint) is the *done gate*; the live conversational tier is
+   *post-deploy evidence* — a deferred live run is then a tracked residual
+   risk, not an assumed pass. The tagula scenario suite is explicit that it
+   is "a data gatherer, NOT a pass/fail test suite": `id|severity|category|
+   message|expected_behavior` rows (196 for the barber), one dedicated caller
+   per stateful flow so conversations do not pollute each other, a cleanup
+   flow for anything that creates real state, a circuit breaker after three
+   consecutive failures, incremental skipping via `passed-ids.txt`, and a
+   JSON report carrying reply + raw response + timing per scenario. A row is
+   "passed" when a reply was *collected*; judging it is a separate step —
+   parallel LLM graders into PASS / PARTIAL / FAIL per category, findings
+   split into **engine bugs** (get a test) and **persona fixes** (get a line
+   in `AGENTS.md`). Every scenario the harness cannot really exercise (a
+   voice note sent as text, a state-dependent slot) is labelled so the
+   report says "state-dependent, not a bug" instead of red.
 2. **Trace the runs you are tuning** (`agent.trace_runs: true`, image
    rebuild, bounded window). A trace answers "which sources did it open, did
    it read the skill, where did the time go"; a reply does not.
 3. **Drift-check after every deploy** (`space-profile check`,
    `compose-grounding.sh check`, `check-extensions.sh`). A gate whose
-   coverage is a hand-maintained list will shrink; derive it from disk.
+   coverage is a hand-maintained list will shrink; derive it from disk, and
+   require every profile to be either covered or exempted *with a written
+   reason* in the gate itself. Two checks tagula's `check-profile-skills.sh`
+   runs that `space-profile check` does not yet: every absolute
+   `/spaces/<id>/…` path an `AGENTS.md` or `SKILL.md` names must resolve
+   ("an agent told to load this finds nothing, and NOTHING reports it"), and
+   every shipped skill directory must be named by the file that indexes it
+   (`ideas/space-profile-check-paths-and-inflight-guard.md`).
 4. **Read the rendered output the way the user does** — on a phone, in the
    group, right-to-left. A mirrored RTL grid and a three-paragraph "short"
    answer both pass every structural test.
@@ -442,10 +576,143 @@ Lessons from four deployments of this shape:
    restart).
 6. **Before calling it done**, the manual check is in
    `docs/pending-verification.md` and the change has run on the live bot.
+7. **Read status from the box, never from the planning docs.** On 2026-08-31
+   three docs said "deploy not yet run" and "space paused" while
+   `space_config` said feed-watch had been on for six days, the ledger held
+   250 runs, and `check` was red on an owner edit nobody had recorded. The
+   status of a profile is: `space-profile check`, `SELECT … FROM task_runs`
+   grouped by day and outcome, `model.active`, and the newest assistant rows
+   — then the docs are corrected to match.
+
+---
+
+## 12. The plan shape — from audit to regression
+
+The football profile was built as a four-milestone goal, and the sequence is
+the reusable part. It is the order in which each step makes the next one
+*measurable*; skipping ahead is how a change ships that nobody can tell
+worked.
+
+```
+0. Audit          read N hours of the real chat; one row per defect with the
+                  message id, the rule it broke, and the layer that owned it
+1. One owner      profile folder + AGENTS.md + apply/check; zero code change
+                  to the bot; every rule now has one home and a drift check
+2. Deterministic  put code in front of the model: a feed, an engine, a
+   input          host-expanded marker — so the model verifies instead of
+                  discovering
+3. Proof          a ledger (one row per run: model, cost, outcome) BEFORE the
+                  change it measures; a pure output lint; fixtures through the
+                  real prompts in a private space; numbers reported, not gated
+4. Regression     one check per audit defect inside `bun run check`; a
+                  re-audit note two weeks later, read from the ledger first
+```
+
+Rules that came with it, each from a decision that was tested against a real
+failure (`docs/goals/football-reporter-profile/decisions.md`):
+
+- **Instrument before the change** (D-012): the ledger was built ahead of
+  feed-watch so the before existed. It is what showed, ten days later, that
+  the deterministic feed cost five times the blind scans.
+- **Mechanisms over rules** (D-016): a defect that comes from *what the model
+  could see* is fixed by changing what it can see — a notebook it reads by
+  rule, a voice removed from the stack — never by a rule about the case. The
+  test: if the fix is a sentence in `AGENTS.md` describing the failure, it is
+  edge-case chasing.
+- **Measure before gating** (D-008): a lint reports for two weeks before it
+  blocks anything; thresholds come from the measured low end, not the median.
+- **Bugs on a parallel track** (D-007): a defect found while building a story
+  is filed, not fixed in place; the story's regression check lands in M4.
+- **Checkpoints are countable** ("0 emoji", "1 `#` title", "one model call per
+  run confirmed in `token_usage`", "$/day reported") and are passed on
+  evidence from the box, with the failures written down next to the passes —
+  the M2 checkpoint records a failed cost direction, which is what makes it
+  worth having.
+- **A decision log with `Revisit if:`** on every entry. Half the football
+  decisions were revisited within ten days (D-013 refined D-003, D-019 re-cut
+  M2.3, D-020 reversed the M1 emoji rule) — a log without the trigger written
+  down is a log that gets argued from memory.
+
+---
+
+## 13. Operating a live profile
+
+What changes once the profile is running and someone else is in the room.
+
+- **The owner will edit the live file.** It is the fastest tuning loop there
+  is — a Hebrew sentence on the box, read by the next run — and it happened
+  four days after "never edit the live `AGENTS.md`" was written. When `check`
+  goes red on the standard itself, **adopt, do not revert**: copy live → repo,
+  `git diff` to see exactly what changed, read the *whole* file for the
+  contradiction the edit introduced (the 08-27 edit allowed club emoji in
+  `## פורמט` while `## סגנון` still said zero), fix that in the repo, commit,
+  then `apply` — which now writes back only the reconciliation (D-020).
+  `apply` over an owner edit deletes four days of judgement to restore a
+  stale copy.
+- **A prose rule that appears on the box is a bug report in disguise.** "No
+  English working sentence as a first line" is the owner describing a host
+  defect in the only layer they can reach. Adopt the sentence (it records
+  intent), file the mechanism (`docs/bugs/…`), and expect the sentence not to
+  hold — four of ten leaks came after it.
+- **Switches with a setter stay out of the manifest, and stay recorded.**
+  `feed-watch.enabled` was deliberately left to a named admin (a verify run
+  executes as whoever set the key). That is right — and it is also how the
+  extension went live with none of its 19 runbook checks walked. When the
+  switch is flipped from chat, the ledger is the record: the first run's
+  timestamp, model and cost go into `pending-verification.md` the same day.
+- **Cost is a per-day number, per space, per outcome.** Read it every few
+  days for the first two weeks:
+  ```sql
+  SELECT date(started_at/1000,'unixepoch') d, outcome, count(*) n, round(sum(cost),2) usd
+  FROM task_runs WHERE space_id='<space>' GROUP BY d, outcome ORDER BY d DESC;
+  ```
+  A space that costs more after the deterministic feed than before it has a
+  configuration problem (run cap, batching, exclusions, a cheaper leg for the
+  quiet path), not a prompt problem.
+- **The model pin is part of the profile's contract but not of its files.**
+  `model.active` lives in `space_config` and the owner switches it from chat.
+  A profile README should say which model it was tuned on; a fixture result
+  should carry the model; a behaviour change that coincides with a switch is
+  the switch until proven otherwise.
+- **Memory needs hygiene, not re-seeding.** After a week the football space had
+  19 episode notes, five of them seeded and the rest napkin's. `check` cannot
+  see a wrong note (a seed is compared for existence only), so the notebook's
+  correctness is verified the way the audit verified the chat: open a sample,
+  check the `## Current State` lines carry `(source, date)`, and look for two
+  notes on one topic — the split-topic failure the seeds were designed to
+  avoid.
+- **Keep the planning docs behind the box, never ahead of it.** The roadmap
+  row says "deployed <date>", the checkpoint block says what passed and what
+  failed with the numbers, and `pending-verification.md` holds only what a
+  person still has to look at. A "deploy not yet run" line that survives the
+  deploy by six days costs the next session an hour.
+- **Ask who is in the room before reading engagement out of the numbers.** On
+  2026-08-31 every mechanical signal on the box — a ledger of successful runs,
+  ambient counts falling to zero, `conversations.last_seen_at` frozen four days
+  back, another space as a live control on the same connection — supported the
+  conclusion that the audience had walked out under the bot's output volume. The
+  space had been re-pointed at a private testing group with one member in it.
+  The box records what was *sent* and what *arrived*; it has no column for what
+  the room is **for**. Membership, purpose and whether a space is a test harness
+  are owner facts. Read the counts, then ask — and write the answer into the
+  profile README, because the next session will re-derive the same wrong story
+  from the same true numbers.
+- **Price the prefix, not the run.** On the Anthropic leg a run's cost is
+  `prefix tokens × $2.50/M` for the first call, then ~1/10 of that per tool
+  round — so `cost/day ≈ runs/day × prefix tokens`. Every byte that reaches the
+  per-run prompt is paid for on every run, whether or not the run reads it. Two
+  things put unbounded content there on `football-friends` in the same week: an
+  extension's `promptAppend` that the host persisted and then replayed through
+  the history window (103 KB), and episode notes whose `## Current State` had no
+  working ceiling (11 KB). Same failure, two doors. The rule: anything injected
+  per run — digests, notebook sections, history — needs a cap that **logs when it
+  bites**, and the stored copy of a turn must be the marker, never the
+  expansion. And read the cost from `cache_write_tokens`, not `input_tokens`;
+  the latter is the uncached sliver and explains nothing.
 
 ---
 
-## 12. Anti-patterns (each one has happened)
+## 14. Anti-patterns (each one has happened)
 
 | Anti-pattern | What it did | Do instead |
 |---|---|---|
@@ -463,10 +730,20 @@ Lessons from four deployments of this shape:
 | Blanket-`cp` of a skill over its deployed copy | `{SPACE}` placeholders reverted; commands broke silently | copy → substitute → diff |
 | Verifying a deploy against the repo | fixes "deployed" that were never built into the image | grep the image / the installed copy |
 | A restart to deploy `container-entry.ts` changes | tracing silently did nothing | image rebuild, then verify in the image |
+| `apply` over an owner's live edit | would have reverted four days of scan-format tuning | adopt live → repo, fix the contradiction, then `apply` (D-020) |
+| A prose rule against a host defect ("no English first line") | four leaks after the rule | file the mechanism; keep the sentence as a record of intent |
+| "Empty runs are cheap" | 46 verify runs/day, 70 % `NO_UPDATE`, $14–20/day for one space | cap runs per hour, batch, exclude; a host pre-filter is the only free run |
+| Assuming the model the profile was tuned on | Sonnet narrated into the sent text where Opus had not | read `model.active` and the ledger's model column first; fixtures carry the model |
+| Status from the planning docs | "deploy not yet run" six days into the deploy | `check` + ledger + `space_config`, then correct the docs |
+| Copying a DM space's permission row into a group | members held `tasks.delete` on the daily article | start from the live row and remove; audit per room |
+| A formatting rule the send pipeline undoes | the model added RLM/RLE marks the host strips before adding its own | read `src/text/rtl.ts` and `markdown.ts`; write only the rules the host does not enforce |
+| "Passed" = a reply was collected | 196 green rows, quality unjudged | grade separately (PASS / PARTIAL / FAIL); split engine bugs from persona fixes |
+| Writing to a live space dir mid-turn | half the old persona, half the new, on a running request | check `state.db`'s last `messages` row before any live write |
+| A ledger or `.db` committed with the profile | one client's records installed into another client's space | create it empty at install; a gate fails on any committed `*.db` |
 
 ---
 
-## 13. Checklist
+## 15. Checklist
 
 - [ ] Kind chosen (applicative vs space) and the layer map written in the README.
 - [ ] Facts inventory done; every fact has a source of truth; every "no answer" has its sentence.
@@ -481,3 +758,12 @@ Lessons from four deployments of this shape:
 - [ ] Extension config owned by the profile where a hand edit would matter; the `enabled`-style switch deliberately not.
 - [ ] Fixtures exist for the rules that matter; a traced run shows the tools/skills being used.
 - [ ] Deployed and verified inside the artefact; `check` clean; the change has run on the live bot.
+- [ ] The ledger existed before the change it measures; the first day's runs × cost per run is written down next to the target.
+- [ ] `persona.exclusive` decided deliberately (owns its standard → on; should still sound like the deployment → off).
+- [ ] Seeds (`workspace_seed`) carry facts and indexes only — no rule that `AGENTS.md` already owns; thin where evidence is thin.
+- [ ] The README names the model the profile was tuned on; the fixture report records the model per result.
+- [ ] Every switch the profile does not own (`*.enabled`) has a line in `pending-verification.md` saying who flipped it and when, taken from `space_config.updated_by` and the ledger.
+- [ ] Every file is classified profile-owned or agent-writable; nothing agent-writable is re-asserted; no `*.db` ships.
+- [ ] Formatting rules are checked against `src/text/rtl.ts` and `src/text/markdown.ts`; the skill's checklist and the lint read one rule list.
+- [ ] `AGENTS.md` has a "what this space does not do" section and a privacy rule phrased as no-retention, not denial.
+- [ ] The bot's own judgements land in an append-only record with a date (notebook `## History`, a tracker, the ledger) so they can be graded later.

package/docs/skills-guide.md

@@ -99,6 +99,23 @@ The `description` is the trigger. It is limited to 1024 characters, and the
 - **Declare state the skill owns** — a DB path, a registry file, a seed —
   and the rule for it ("register every new tracker in `registries.json` or it
   disappears").
+- **A formatting skill states what the host already does, then only what it
+  does not.** The investor `whatsapp-formatting` skill opens by saying that
+  `applyRtlDirection` (`src/text/rtl.ts`) strips leading bidi marks and adds
+  its own RLM per line — "verified against this install's runtime" — so the
+  model must *not* add RLE/RLM; what remains its job is to start every line
+  with a Hebrew word or an emoji, never a ticker or a number. Same for
+  `normalizeChatMarkdown` (`src/text/markdown.ts`): headings and `**` are
+  rewritten at send, so a rule about them is a rule about the stored row,
+  not the rendered message. End the skill with a short checklist the model
+  runs before sending; the same list is what the output lint asserts
+  (`profile-guide.md` §7, §11) — one list, two readers.
+- **Exit codes are a table with a "what you do" column.** The investor
+  `chart` skill lists every code, says which are structural (never retry —
+  "a chartless analysis is a fine answer, a stalled reply is not") and adds
+  a "how it works, for whoever maintains this" section so the next editor
+  does not "simplify" it into a different data source with silently wrong
+  numbers.
 
 ## 5. Making a profile actually use its skills
 
@@ -152,3 +169,10 @@ then `diff` and confirm the only difference is the placeholder.
       a container (`docker run --rm --entrypoint ls <image> /home/mercury/.pi/agent/skills`
       for global ones) or check `<available_skills>` in a trace.
 - [ ] A trace of one real run shows the `read` of `SKILL.md`.
+- [ ] Every absolute path the skill or `AGENTS.md` names resolves inside the
+      space (tagula gates this with `check-profile-skills.sh`; for a space
+      profile, `ls` them from the box until `space-profile check` learns to —
+      `docs/ideas/space-profile-check-paths-and-inflight-guard.md`).
+- [ ] If the skill is about formatting, it names the host passes that already
+      run at send (`src/text/rtl.ts`, `src/text/markdown.ts`) and only rules
+      beyond them.

package/examples/extensions/feed-watch/config.ts

@@ -21,6 +21,16 @@ export const MAX_TERMS = 50;
 export const MAX_PER_HOUR_CEILING = 12;
 export const MAX_BATCH_MINUTES = 30;
 
+/**
+ * Most items the daily digest will carry. A bound, not a tuning knob: the
+ * buffer is already capped at `BUFFER_CAP` items, but that ceiling was chosen
+ * for the store, not for a prompt, and 264 items came to 103 KB before anyone
+ * measured it. Whatever the watcher collects, the article's prompt stops here
+ * — and says so in the log when it does.
+ */
+export const DEFAULT_DIGEST_MAX_ITEMS = 200;
+export const DIGEST_MAX_ITEMS_CEILING = 400;
+
 /** An RSS/Atom URL, polled as-is. */
 export interface RssSource {
   type: "rss";
@@ -60,6 +70,8 @@ export interface WatchConfig {
   quietHours: QuietHours | null;
   maxPerHour: number;
   batchMinutes: number;
+  /** Hard ceiling on how many items the daily digest hands the article. */
+  digestMaxItems: number;
   /** IANA zone, or "" to fall back to the deployment default and then UTC. */
   timezone: string;
 }
@@ -158,6 +170,14 @@ export function isValidBatchMinutes(value: string): boolean {
   return isIntInRange(value, 0, MAX_BATCH_MINUTES);
 }
 
+/**
+ * At least one: a digest of zero items is indistinguishable from "the watcher
+ * is not running", which the article is explicitly told to treat differently.
+ */
+export function isValidDigestMaxItems(value: string): boolean {
+  return isIntInRange(value, 1, DIGEST_MAX_ITEMS_CEILING);
+}
+
 /**
  * An IANA zone name, checked by asking `Intl` to use it. Empty means "unset",
  * which is a valid state — the poller falls back to the deployment default.
@@ -270,6 +290,16 @@ export function readSpaceConfig(
         log,
       ),
     ),
+    digestMaxItems: Number(
+      read(
+        getConfig,
+        spaceId,
+        "digest_max_items",
+        String(DEFAULT_DIGEST_MAX_ITEMS),
+        isValidDigestMaxItems,
+        log,
+      ),
+    ),
     timezone: read(
       getConfig,
       spaceId,
@@ -344,6 +374,12 @@ export const CONFIG_KEYS: ConfigKeyDef[] = [
     default: String(DEFAULT_BATCH_MINUTES),
     validate: isValidBatchMinutes,
   },
+  {
+    key: "digest_max_items",
+    description: `Most items the daily digest carries into the article's prompt, newest first (1–${DIGEST_MAX_ITEMS_CEILING}, default ${DEFAULT_DIGEST_MAX_ITEMS}). Older matches stay in the workspace digest file. A bound on prompt size, not a filter.`,
+    default: String(DEFAULT_DIGEST_MAX_ITEMS),
+    validate: isValidDigestMaxItems,
+  },
   {
     key: "timezone",
     description: