@lorekit/cli 1.69.0 → 1.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.69.0",
+  "version": "1.70.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/skill/lorekit-groom/rules/grooming-pass.md

@@ -60,6 +60,14 @@ Findings are structural, not semantic — each names its rule:
   entry has no `kind`, so it renders as a raw JSON blob in every SessionStart
   digest instead of being excluded by `isGeneralLesson`. Set `--kind bus` or
   `--kind signal` on the record.
+- **hidden-metadata** — the body carries an HTML comment, a leading front-matter
+  block, or a `key=value` header before the `#` title. This is the **repudiated
+  legacy `<!-- meta: seen_count=… status=… trigger-context=… -->` convention** the
+  `lorekit-setup` skill once prescribed and now forbids: an HTML comment renders to
+  nothing (so a human sees a lesson starting mid-sentence) while a baked-in
+  `seen_count` / `status` / `trigger` silently disagrees with the store's own
+  column / tag / field. **This is grooming's job to clean, not just report** — see
+  the cleanup step below.
 
 These are the cheapest wins and the least controversial, so clear them first.
 For each: either **fix it in place** (rewrite a too-short value into a real
@@ -68,6 +76,32 @@ updates in place) or, if the lesson is genuinely empty of meaning, **queue it fo
 removal** in the plan. `lint` exits non-zero while findings remain, which also
 makes it a clean CI gate — a passing `lint` is your Phase 6 proof.
 
+### Cleaning a `hidden-metadata` finding (fold, then strip)
+
+A hidden-metadata lesson is **fixed in place**, never deleted for it (the prose is
+usually a real lesson wearing a bad header). Recover the facts into their proper
+homes, then strip the block:
+
+1. **Read the whole record** (`lorekit show <scope::key> --json`) so you see the raw
+   body, including the `<!--` block the SessionStart digest hides.
+2. **Fold each buried fact into its first-class home**, never back into prose:
+   - `seen_count=N` → **drop it entirely.** The column is the only true copy; a
+     baked number is stale. Do not try to "restore" it — the store's counter is
+     authoritative.
+   - `status=structural` / `status=promoted` → a `status::<value>` **tag** on the write.
+     (`status=active` is the default — drop it.)
+   - `trigger-context="…"` → the visible **`Applies when:`** line at the top of the
+     body, and/or the `trigger` **field** for the category.
+   - `expires=…` / `ttl=…` → a `ttl_days` on the write.
+3. **Rewrite the body as pure markdown** to the lesson shape (takeaway title →
+   `Applies when` → bold-labelled paragraphs), with the `<!--`/front-matter/header
+   gone, via a `memory.write` to the same `scope`+`key` (updates in place, carrying
+   the recovered tags/fields).
+4. **Re-lint** the record to confirm `hidden-metadata` no longer fires.
+
+Do this whenever a pass surfaces the finding — that is how the store stops
+re-teaching the pattern to the next agent that reads a neighbouring lesson.
+
 ## Phase 3 — Dedupe (read-only)
 
 ```bash

package/skill/lorekit-setup/SKILL.md

@@ -1,31 +1,29 @@
 ---
 name: lorekit-setup
 description: >
-  Sets up a self-improvement loop for a skill, workflow, or agent using LoreKit,
-  so a host gets better across runs by reading its own accumulated lessons at
-  the start of every run and hardening the proven ones into permanent rules.
-  Designs the lessons loop (a fast episodic tier of LoreKit lessons, advisory-only;
-  a slow procedural tier that promotes a recurring lesson into a host rule; and,
-  for the rarer judgement-free, independently-checkable case, a third rung that
-  compiles a recurring lesson into a mechanically-enforced CI invariant instead),
-  chooses the lesson bucket (tag + key namespace) and scopes, and installs the
-  entrenchment guards that stop a learning loop from reinforcing its own
-  mistakes. Also covers the non-LLM case: giving a deterministic job (a GitHub
-  Actions workflow, a cron script, a release pipeline) durable JSON state
-  records so it knows what happened on its last run — flaky tests, a benchmark
-  baseline, the last deployed SHA — in the same store agents read. Runtime
-  reading and writing of lessons is the lorekit-memory skill; this is the
-  authoring counterpart. Use when giving a host durable cross-run memory or
-  wiring a lessons loop. Triggers on "set up memory for my skill", "add a
-  self-improvement loop", "give my workflow memory", "make this learn from its
-  mistakes", "self-improving memory", "memory in CI", "GitHub Actions state",
-  "remember the last CI run", "/lorekit-setup".
+  Turns a skill, workflow, agent, or CI job into one that gets better across runs
+  and can PROVE it. Walks a six-step lifecycle — Find where a loop pays off, Wire
+  it from a ready-made recipe card, Seed it so it delivers on run one, Prove it
+  improved something, Maintain it so it does not rot, and Scale it to a team — with
+  a 15-minute quickstart that ends in a loop firing once, live. Under the hood it
+  is a LoreKit lessons loop: a fast episodic tier of advisory lessons read at the
+  start of every run and written on failure; a slow procedural tier that promotes a
+  recurring lesson into a permanent rule; and, for the rare judgement-free case, a
+  third rung that compiles a lesson into a mechanically-checked CI invariant. Also
+  covers the non-LLM case (durable JSON state records for a deterministic job) and
+  the guards that stop a learning loop from reinforcing its own mistakes. Runtime
+  reading and writing of lessons is the lorekit-memory skill; this is the authoring
+  counterpart. Use when giving a host durable cross-run memory or wiring a lessons
+  loop. Triggers on "set up memory for my skill", "add a self-improvement loop",
+  "give my workflow memory", "make this learn from its mistakes", "where should I
+  add a loop", "prove my loop is working", "self-improving memory", "memory in CI",
+  "GitHub Actions state", "remember the last CI run", "/lorekit-setup".
 user-invocable: true
 argument-hint: '[host-name]'
 license: MIT
 metadata:
   author: mthines
-  version: '1.0.0'
+  version: '2.0.0'
   workflow_type: memory-loop-authoring
   tags:
     - lorekit
@@ -41,40 +39,74 @@ metadata:
 
 # LoreKit Setup
 
-Give a host durable cross-run memory. For a model-driven host that means a
-**self-improvement loop**: it reads its own accumulated lessons at the start of
-every run and hardens the proven ones into permanent rules, so it gets better the
-more it runs. For a deterministic host — a CI job — it means **state records**: it
-reads what was true at the end of its last run instead of rediscovering it.
-
-This is the **authoring** counterpart to `lorekit-memory`. `lorekit-memory` does
-the runtime read/write of individual lessons; `lorekit-setup` wires the durable
-memory that calls those primitives on a host's behalf. Both run on the same
-LoreKit store — over the `memory.*` MCP tools for agents, over the `lorekit` CLI
-or REST for jobs.
-
-## The rungs of a lessons loop (in one screen)
-
-The runtime loop below is two tiers, fast and slow; a third, rarer rung sits past
-promotion, for the minority of recurring lessons that can be turned into a
-mechanically-checked rule instead of text a reader has to notice.
-
-| Rung | Mechanism | Changes behavior? | Advisory or enforced? |
-| ---- | --------- | ----------------- | ---------------------- |
-| **Fast (episodic)** | LoreKit lessons in a per-host bucket, read at the start of a run, written on failure | **No** — advisory input only | Advisory |
-| **Slow (procedural)** | A human-reviewed edit that hardens a recurring lesson into a host rule | **Yes** | Advisory (works only if the next reader notices it) |
-| **Compiled invariant** | A declarative `obligations-map.mjs` entry a CI gate checks against a changed-file set — see [rules/compiled-invariants.md](./rules/compiled-invariants.md) | **Yes** | Enforced once `gating`; most lessons never qualify |
-
-A recurrence gate connects the first two: a lesson that recurs (`seen_count >= 3`)
-or carries the `status::structural` tag becomes promotion-eligible. Entrenchment guards
-keep the fast tier from reinforcing its own wrong conclusions. The third rung has
-its own, stricter gate — the compilability test — and most promotion-eligible
-lessons stop at the second rung because they fail it.
-
-## Pick the shape first
-
-Two kinds of host want memory, and they want a different record. Decide which
-before reading further:
+Give a host durable cross-run memory, and make its improvement **visible**. For a
+model-driven host that means a **self-improvement loop**: it reads its own
+accumulated lessons at the start of every run and hardens the proven ones into
+permanent rules, so it gets better the more it runs. For a deterministic host — a
+CI job — it means **state records**: it reads what was true at the end of its last
+run instead of rediscovering it.
+
+This is the **authoring** counterpart to `lorekit-memory`. `lorekit-memory` does the
+runtime read/write of individual lessons; `lorekit-setup` wires the durable memory
+that calls those primitives on a host's behalf. Both run on the same LoreKit store —
+over the `memory.*` MCP tools for agents, over the `lorekit` CLI or REST for jobs.
+
+> A loop that nobody can see helping is indistinguishable from no loop. This skill
+> treats "the host measurably got better" as the deliverable — not "a loop is
+> wired." Every step below is judged against that.
+
+## The lifecycle (start here)
+
+A working loop is six steps. Do them in order; each links to the rule that covers it.
+
+| # | Step | What it answers | Read |
+| - | ---- | --------------- | ---- |
+| 1 | **Find** | *Where* does a loop actually pay off? (Do not guess — the data already knows.) | [rules/self-improvement-loops.md § Find where a loop pays off](./rules/self-improvement-loops.md#find-where-a-loop-pays-off) |
+| 2 | **Wire** | Add the read/write steps with the least effort — copy a recipe card. | [templates/](./templates/) + [rules/self-improvement-loops.md](./rules/self-improvement-loops.md) |
+| 3 | **Seed** | Deliver value on run **one**, before any lesson has been earned. | [rules/cold-start-seeding.md](./rules/cold-start-seeding.md) |
+| 4 | **Prove** | Show the loop reduced a real failure — not just that lessons exist. | [rules/proving-improvement.md](./rules/proving-improvement.md) |
+| 5 | **Maintain** | Keep it firing, keep the bucket clean, roll back a bad lesson. | [rules/loop-health.md](./rules/loop-health.md) |
+| 6 | **Scale** | Turn one person's loop into a team practice that compounds. | [rules/team-and-portfolio.md](./rules/team-and-portfolio.md) |
+
+If invoked with a `host-name`, set up memory for that host and walk this lifecycle.
+Otherwise ask which skill / workflow / agent / job it is for, pick the shape from
+[Pick the shape](#pick-the-shape), then walk it.
+
+## Quickstart (15 minutes, one loop firing once)
+
+The shortest path from "I have a host" to "I watched the loop close." Do it against a
+real host with `memory.*` connected.
+
+1. **Name the bucket.** From the host's name `<host>`: tag `loop::<host>-lessons`,
+   key namespace `<host>-lessons::<slug>`. One bucket per host.
+2. **Copy a recipe card.** Pick the archetype in [templates/](./templates/) that
+   matches your host (code-changing agent, reviewer/reconcile host, multi-step
+   orchestrator, CI job) and paste its read step at the host's start and its write
+   step at the host's existing failure points. The card already carries the
+   injection cap, the TTL, and the entrenchment defaults — do not hand-roll them.
+3. **Seed one real lesson** (optional but recommended) so run one is not empty —
+   [rules/cold-start-seeding.md](./rules/cold-start-seeding.md). Keep it to a
+   *handful*, hand-checked.
+4. **Fire it once, on purpose.** Trigger the failure the loop is meant to catch.
+   Confirm a lesson was written to the right scope with the right tag:
+
+   ```text
+   memory.list { scope: "<the scope you expect>", tags: ["loop::<host>-lessons"], limit: 10 }
+   ```
+
+5. **Run again and watch it read back.** Start a second run over the same
+   situation. Confirm the lesson surfaces in the read step and biases the run.
+   That is the loop closing — the whole point, demonstrated once.
+6. **Write down the success metric** you will use to prove it keeps helping —
+   [rules/proving-improvement.md](./rules/proving-improvement.md). The required one
+   is the *immunity re-challenge*: after you promote a lesson to a rule, the failure
+   signature should stop recurring.
+
+That is a live, working loop. Everything below is depth on each step.
+
+## Pick the shape
+
+Two kinds of host want memory, and they want a different record. Decide which first:
 
 | The host is… | Wants | Read |
 | ------------ | ----- | ---- |
@@ -85,20 +117,44 @@ before reading further:
 A host can want both, in separate buckets: the state record carries *what is true
 right now*, the lesson carries *what we learned about it*.
 
-## Set up a loop (model-driven hosts)
+## The rungs of a lessons loop (in one screen)
 
-Follow [rules/self-improvement-loops.md](./rules/self-improvement-loops.md).
-It covers: when to add a loop (and when not to), the bucket convention (tag
-`loop::<host>-lessons` + key namespace), scope selection, the lesson schema, the
-read/write steps, the promotion gate, the entrenchment guards, a wiring
-checklist, and an interactive setup flow.
+The runtime loop is two tiers, fast and slow; a third, rarer rung sits past promotion.
+
+| Rung | Mechanism | Changes behavior? | Advisory or enforced? |
+| ---- | --------- | ----------------- | ---------------------- |
+| **Fast (episodic)** | LoreKit lessons in a per-host bucket, read at the start of a run, written on failure | **No** — advisory input only | Advisory |
+| **Slow (procedural)** | A human-reviewed edit that hardens a recurring lesson into a host rule | **Yes** | Advisory (works only if the next reader notices it) |
+| **Compiled invariant** | A declarative `obligations-map.mjs` entry a CI gate checks against a changed-file set — see [rules/compiled-invariants.md](./rules/compiled-invariants.md) | **Yes** | Enforced once `gating`; most lessons never qualify |
+
+A recurrence gate connects the first two: a lesson that recurs (`seen_count >= 3`) or
+carries the `status::structural` tag becomes promotion-eligible. Entrenchment guards
+keep the fast tier from reinforcing its own wrong conclusions.
+
+## Non-negotiables (do not "optimize these away")
+
+Five co-requirements make the difference between a loop that helps and one that
+quietly rots or crowds out the run it was meant to help. Every recipe card bakes
+them in; if you wire by hand, wire these too:
+
+1. **A lesson body is markdown for humans — nothing hidden.** No HTML comment, no
+   front-matter, no JSON blob, no `key=value` header. Every fact the store already
+   models goes in its own field, never restated in prose — see
+   [the body contract](#a-lesson-body-is-markdown-for-humans--nothing-hidden) below.
+2. **Every loop declares a per-host injection cap.** A loop reads *at most* N lessons
+   into a run (the cards default to a small N). Many cheap loops with no cap tax
+   every session's context until agents ignore injected lore entirely.
+3. **Every lesson expires.** `ttl_days` on the write, refreshed on recurrence, so a
+   stale belief decays instead of entrenching. Decay is automatic, never staffed.
+4. **Lessons are advisory, never auto-applied.** The only path from a lesson to
+   changed behavior is the human-reviewed slow tier.
+5. **Prove it, or it did not happen.** A loop earns its keep only when a real failure
+   stops recurring — [rules/proving-improvement.md](./rules/proving-improvement.md).
 
 ### A lesson body is markdown for humans — nothing hidden
 
-Whatever host you wire, its write step carries one non-negotiable contract: the
-`value` is **markdown a person reads**, and it carries no HTML comment, no
-front-matter, no JSON blob, and no `key=value` header. Every fact the store
-already models goes in its own write field, never restated in the prose:
+The `value` is **markdown a person reads**, and it carries no hidden payload. Every
+fact the store already models goes in its own write field:
 
 | Fact | Field, not prose |
 | ---- | ---------------- |
@@ -109,46 +165,27 @@ already models goes in its own write field, never restated in the prose:
 | Repo / branch / commit / PR | the `origin_*` fields |
 | What triggered the write | `trigger` |
 
-A hidden block does not just look untidy — it is *wrong*. A `seen_count=1` baked
-into prose is stale the first time the lesson recurs, while the column that
-governs promotion moves without it, and a markdown reader is shown a lesson that
-begins mid-sentence. Structure the prose instead: a takeaway title, a visible
-**Applies when** line, then short bold-labelled paragraphs under ~1,500
-characters. The full shape, the field-by-field rationale, and the writing rules
-are [the lesson record](./rules/self-improvement-loops.md#the-lesson-record).
+A hidden block does not just look untidy — it is *wrong*. A `seen_count=1` baked into
+prose is stale the first time the lesson recurs, while the column that governs
+promotion moves without it; an HTML comment renders to nothing, so a human is shown a
+lesson that begins mid-sentence. The full shape, the field-by-field rationale, and the
+writing rules are [the lesson record](./rules/self-improvement-loops.md#the-lesson-record).
+This contract is now checkable — `lorekit lint` flags a body that violates it, and the
+`lorekit-groom` skill cleans legacy offenders.
 
 ## The shared codebase-knowledge layer (automatic cross-loop synergy)
 
-A per-host lessons bucket is private to one host. There is also **one shared
-bucket every code-touching host reads and, under a contract, writes**:
-`codebase-knowledge` — a repo-scoped, structurally-keyed record
-(`knowledge::<symbol>@<path>` facts, `hotspot::<path>` counters) of what the
-codebase has taught every LoreKit loop that touched it. Because the name is fixed
-and the key is structural, a loop wired by one person compounds with a loop wired
-by another: a host about to change code reads the history for exactly the files it
-will touch, and a host that verifies a structural fact contributes it back. That
-is the synergy that appears for a user who wired a single skill and nothing else.
-
-Wire it whenever a host changes code (read at its plan/apply seam) or verifies a
-durable structural fact (write under the contract). The full specification — the
-bucket table, the automatic read side, and the seven-bullet multi-writer write
-contract — is [rules/self-improvement-loops.md § Shared codebase-knowledge](./rules/self-improvement-loops.md#shared-codebase-knowledge-the-standard-cross-loop-layer).
-
-## Set up CI state (deterministic hosts)
-
-Follow [rules/ci-state-records.md](./rules/ci-state-records.md). It covers: when
-LoreKit beats `actions/cache` (and when it does not), the `ci::<job>-state` bucket
-convention, the versioned JSON envelope, the read/write steps with the `lorekit`
-CLI or REST, a full GitHub Actions example, the guards (bounded cardinality, no
-secrets, explicit expiry, never on the critical path, last-write-wins), and a
-wiring checklist.
-
-If invoked with a `host-name`, set up memory for that host; otherwise ask which
-skill / workflow / agent / job it is for, pick the shape from the table above,
-then walk that rule file's setup.
-
-A lessons loop's runtime tier needs LoreKit's `memory.*` tools connected; if they
-are not, the host's loop is a silent no-op (the slow tier — a normal source edit —
-still works). A CI job needs a `lk_*` token in its environment instead, and
-degrades to its first-run path when the store is unreachable. Designing either
-needs no connection.
+A per-host lessons bucket is private to one host. There is also **one shared bucket
+every code-touching host reads and, under a contract, writes**: `codebase-knowledge` —
+a repo-scoped, structurally-keyed record (`knowledge::<symbol>@<path>` facts,
+`hotspot::<path>` counters) of what the codebase has taught every LoreKit loop that
+touched it. Because the name is fixed and the key is structural, a loop wired by one
+person compounds with a loop wired by another. The full specification is
+[rules/self-improvement-loops.md § Shared codebase-knowledge](./rules/self-improvement-loops.md#shared-codebase-knowledge-the-standard-cross-loop-layer).
+
+## Connectivity
+
+A lessons loop's runtime tier needs LoreKit's `memory.*` tools connected; if they are
+not, the host's loop is a silent no-op (the slow tier — a normal source edit — still
+works). A CI job needs a `lk_*` token in its environment instead, and degrades to its
+first-run path when the store is unreachable. Designing either needs no connection.

package/skill/lorekit-setup/rules/cold-start-seeding.md

@@ -0,0 +1,102 @@
+# Cold-start seeding — value on run one
+
+The honest cold start is a lie. A loop does not really begin empty — the lessons already
+exist, scattered across git history, PR review threads, CI guard scripts, and the
+`obligations-map`. They were just never written down as reusable memory. Seeding
+harvests a *handful* of them so the loop's very first run reads real institutional
+knowledge instead of nothing.
+
+This is optional, and it trades one thing for another — read
+[the measurement trade-off](#the-hard-rule-never-seed-a-loop-you-will-measure) before
+you reach for it.
+
+## Contents
+
+- [When to seed (and when not to)](#when-to-seed-and-when-not-to)
+- [The cap: a handful, hand-checked](#the-cap-a-handful-hand-checked)
+- [The hard rule: never seed a loop you will measure](#the-hard-rule-never-seed-a-loop-you-will-measure)
+- [Where the lessons already are](#where-the-lessons-already-are)
+- [The flow](#the-flow)
+- [Guards](#guards)
+
+---
+
+## When to seed (and when not to)
+
+Seed when the host's value is **invisible for its first week** — lessons only accrue on
+repeated runs, so a freshly-wired loop delivers config, not a win, and people abandon
+it before it pays off. A few real seeded lessons make run one useful.
+
+Do **not** seed when you intend to *prove* the loop's lift (below), or when you cannot
+find genuinely recurring pain to seed from — a fabricated lesson is worse than an empty
+bucket.
+
+## The cap: a handful, hand-checked
+
+**Seed a handful (roughly ≤ 5), each one hand-checked. Never bulk-mine.** This is the
+single most important rule here, and it runs against the instinct to "import everything."
+
+Bulk seeding floods the bucket with generic, machine-drafted lessons that never get
+opened. That tanks the exact pull-through ratio [proving-improvement.md](./proving-improvement.md)
+reads, triggers the bucket-bloat [loop-health.md](./loop-health.md#keep-the-bucket-from-bloating)
+fights, and buries the few seeds that were actually good — on day one. A small,
+curated set is worth more than a large, automatic one.
+
+## The hard rule: never seed a loop you will measure
+
+Seeding writes lessons before the loop has run, so it **erases the clean baseline** the
+immunity re-challenge needs. A seeded loop's improvement is unattributable — you cannot
+tell the loop's own learning from the head start you handed it.
+
+So it is one or the other, per loop:
+
+| You want… | Then… |
+| --------- | ----- |
+| Value on run one | Seed it (a handful, curated). Accept that its lift is not cleanly provable. |
+| Provable lift | Leave it cold. The first weeks are quieter, but the immunity check reads a real baseline. |
+
+## Where the lessons already are
+
+Mine these — they are recurring pain the team already paid for:
+
+- **Git fix/revert chains** — the same pattern fixed the same way 3+ times, or a
+  revert-then-refix. `git log`, `git log --grep=revert`, `git log -p` over a hot file.
+- **Recurring PR review comments** — the same review note left across many PRs.
+- **Existing CI guard scripts** — a guard that exists *is* a lesson someone learned;
+  seed a `codebase-knowledge` fact pointing at it.
+- **The `obligations-map`** — its path-keyed partnerships are compiled lessons; the
+  ones not yet gating are candidates. `lorekit invariants candidates` surfaces clusters.
+- **`lorekit dedupe`** — near-duplicate existing lessons that should be one seed.
+
+## The flow
+
+1. **Mine** one or two of the sources above for genuinely recurring pain.
+2. **Draft** ≤ 5 candidate lessons to the normal body shape
+   ([the lesson record](./self-improvement-loops.md#the-lesson-record)) — a takeaway
+   title, a concrete **Applies when**, a prescriptive **Do this instead**.
+3. **A human approves** the survivors. This is not skippable; seeding is the one place
+   a bad lesson enters with no recurrence evidence behind it.
+4. **Write** each with provenance and a `source::seed` tag, so seeds are auditable and
+   distinguishable from earned lessons:
+
+   ```text
+   memory.write {
+     scope:       "<global | repo::<owner>/<repo>>",
+     key:         "<host>-lessons::<slug>",
+     value:       "<markdown lesson body — no hidden blocks>",
+     tags:        ["loop::<host>-lessons", "source::seed"],
+     trigger:     "manual",
+     origin_commit: "<the commit this was learned from, if any>",
+     ttl_days:    90
+   }
+   ```
+
+## Guards
+
+- **The body contract still applies** — seeds are markdown for humans, no hidden blocks.
+- **Tag seeds `source::seed`** so [loop-health](./loop-health.md) and grooming can tell a
+  head start from an earned lesson.
+- **Privacy pre-flight is not skipped** — a seed mined from history can carry a secret or
+  a name; drop it, do not write it. The bar is stricter for `repo::` (team-visible).
+- **Re-check the cap after mining.** If your candidate list is 40 long, you are
+  bulk-seeding — cut to the handful that actually recur.

package/skill/lorekit-setup/rules/loop-health.md

@@ -0,0 +1,117 @@
+# Loop health — keeping it firing, clean, and honest
+
+A wired loop is not a working loop. This file is the maintenance layer: how to tell the
+loop is firing at all, how to catch a lesson that will never match the read that should
+surface it, how to roll back a bad lesson without losing the evidence, how to stop the
+bucket bloating, and how to keep every body honest. Most of it is a check you run once
+at wiring time; the rest the `lorekit-groom` skill automates.
+
+## Contents
+
+- [Is the loop firing?](#is-the-loop-firing)
+- [Does the write match the read? (matchability check)](#does-the-write-match-the-read-matchability-check)
+- [Rolling back a bad lesson: quarantine, not delete](#rolling-back-a-bad-lesson-quarantine-not-delete)
+- [Keep the bucket from bloating](#keep-the-bucket-from-bloating)
+- [The body contract is now enforced](#the-body-contract-is-now-enforced)
+
+---
+
+## Is the loop firing?
+
+The most common silent failure is a loop that never runs — a read step behind a
+condition that is never true, or a `memory.*` connection that quietly dropped. Silence
+looks identical to "no failures happened."
+
+Turn the absence into a presence with a **canary**: at wiring time, plant one canary
+lesson per bucket with a unique key and a `ttl_days` shorter than the loop's cadence.
+
+```text
+memory.write {
+  scope:    "repo::<owner>/<repo>",
+  key:      "<host>-lessons::canary",
+  value:    "# Canary — if the read step surfaced this, the loop's read path works.",
+  tags:     ["loop::<host>-lessons", "status::canary"],
+  trigger:  "manual",
+  ttl_days: <shorter than the loop's run cadence>
+}
+```
+
+If the loop is alive, its own read/write touches the canary and the store's usage
+telemetry records it; if the canary quietly expires without ever being touched, the loop
+is not firing — a diagnosable signal where silence was not. Check recency with
+`lorekit stats` / `lorekit list --tags loop::<host>-lessons`. Exclude `status::canary`
+from the run's actual considerations.
+
+## Does the write match the read? (matchability check)
+
+A lesson that the read step will never surface is dead on arrival — and you only find
+out much later, when the same failure recurs and the loop "did not help." The only
+moment you can catch it is at **write** time, when you still know what the lesson was
+supposed to catch.
+
+Right after writing a failure lesson, re-query the store with the **same terms the read
+step uses** and confirm the just-written lesson comes back:
+
+```text
+memory.search { q: "<the failure's key terms>", scopes: ["repo::<owner>/<repo>", "global"], limit: 10 }
+# Is the lesson you just wrote in the results? If not, its tags / Applies-when / scope
+# do not match how the read step looks for it — fix them NOW, while you have the context.
+```
+
+A miss means a mismatch between how the lesson was written and how it will be sought —
+usually a too-specific **Applies when**, a wrong scope, or a missing tag. Fixing it at
+write time is cheap; discovering it at the next failure is not.
+
+## Rolling back a bad lesson: quarantine, not delete
+
+A loop can store a wrong conclusion. Deleting it destroys the evidence of *what the
+agent believed* when it got stuck — which is exactly the forensic value you want right
+after the harm. Prefer a reversible demotion:
+
+1. **Quarantine** the suspect lesson: add a `status::quarantine` tag and shorten its
+   `ttl_days`. The start-of-run read filters `status::quarantine` OUT, so it stops
+   biasing runs, but it survives long enough for a human to inspect it.
+2. **Inspect**, decide: rewrite it (a real lesson, badly phrased) or let it expire (a
+   genuine mistake).
+3. **Protect** a lesson a human has vetted with `memory.protect`, so grooming and
+   auto-quarantine never touch it.
+
+Delete only a lesson that is both wrong *and* worthless to inspect. Quarantine is the
+default; deletion is the exception.
+
+## Keep the bucket from bloating
+
+Every lesson in a bucket competes for the run's read budget. Two mechanisms keep it
+bounded:
+
+- **The injection cap (a wiring precondition).** The loop reads at most N lessons into a
+  run (the recipe cards default N = 5). This bounds read cost *regardless* of how big the
+  bucket grows — it is the backstop.
+- **Grooming.** Run the `lorekit-groom` skill periodically to merge near-duplicates,
+  expire the stale, and retire the never-opened (low pull-through). Grooming is where a
+  bucket's total size is actually reduced; the cap only bounds what a single run reads.
+
+A bucket whose read is always dominated by low-value lessons is a grooming problem, not
+a reason to raise the cap.
+
+## The body contract is now enforced
+
+Every lesson body is markdown for humans — no HTML comment, no front-matter, no JSON
+blob, no `key=value` header ([the full contract](./self-improvement-loops.md#never-put-machine-metadata-in-the-body)).
+This is no longer honor-system:
+
+- **`lorekit lint` flags a violation.** A body containing `<!-- meta` / any `<!--`
+  block, leading front-matter (`---`), or a `key=value` header before the `#` title is
+  reported by the `hidden-metadata` lint rule. Run `lorekit lint` after a batch of
+  writes.
+- **The `lorekit-groom` skill cleans legacy offenders.** The store still contains records
+  written under the old `<!-- meta: seen_count=… status=… trigger-context=… -->`
+  convention (which this skill once prescribed and now forbids); grooming detects them,
+  folds any recoverable value into the proper column/tag/field, and strips the block. See
+  the `lorekit-groom` skill.
+- **The matchability check above** is the natural moment to also eyeball the body: if you
+  find yourself reaching for a compact hidden header, stop — every fact in it has a
+  first-class field.
+
+Never write a hidden block. It renders to nothing for a human and its baked-in values
+silently disagree with the store's own columns.