@lorekit/cli 1.68.0 → 1.70.0

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.

package/skill/lorekit-setup/rules/proving-improvement.md

@@ -0,0 +1,111 @@
+# Proving a loop improved something
+
+A loop that nobody can see helping is indistinguishable from no loop. Wiring is not
+the deliverable — **a real failure that stops recurring** is. This file is how you show
+that, and — as important — how you avoid fooling yourself with numbers that cannot prove
+it.
+
+## Contents
+
+- [The required proof: the immunity re-challenge](#the-required-proof-the-immunity-re-challenge)
+- [Why the raw counters cannot prove causation](#why-the-raw-counters-cannot-prove-causation)
+- [The optional counter view (advisory only)](#the-optional-counter-view-advisory-only)
+- [Declare the metric at wiring time](#declare-the-metric-at-wiring-time)
+- [The north star: a withheld-memory control arm](#the-north-star-a-withheld-memory-control-arm)
+- [Guards](#guards)
+
+---
+
+## The required proof: the immunity re-challenge
+
+There is exactly one proof this skill *requires*, because it is the one a doc can make
+a person actually run and the one that survives the confounds below: **after you promote
+a lesson to a rule, its failure signature should stop recurring.**
+
+Borrowed from immune memory: promoting a lesson registers its original failure
+signature as a "pathogen"; a later write bearing that same signature is a re-infection.
+
+1. **At promotion, record the signature.** The lesson's **Applies when** line *is* the
+   signature — a file glob, a task type, a tool name, an error shape. Note the source
+   lesson's key and its `seen_count` at the moment of promotion.
+2. **Watch for recurrence.** The direct measurement is the source lesson's `seen_count`
+   going **flat** — the loop stops writing that lesson because the failure stopped
+   happening. Read the column (`memory.read` / `lorekit show`), never a number in the
+   body.
+3. **Escalate a breakthrough.** Any new write matching the promoted signature is a
+   vaccine-breakthrough case: the rule did not hold. That is a signal to fix the rule
+   (too narrow, wrong shape), not to shrug.
+
+A promoted rule's value is the **silence** of its failure signature afterward. You
+measure the absence. This needs no new product feature — `seen_count` and the
+**Applies when** line already exist.
+
+## Why the raw counters cannot prove causation
+
+It is tempting to prove a loop "works" by pointing at rising counters. Do not lead with
+this — LoreKit's own analysis records why the absolute counters are confounded:
+
+- **`read_count` is ~99.8% bulk ride-alongs** — it tracks scope breadth, not whether a
+  lesson mattered.
+- **`seen_count` is `1` for ~88% of rows** — most lessons never recur, so a raw count is
+  mostly noise.
+- **Pull-through (`opened_count / read_count`) is the only trustworthy value signal** —
+  it cancels the ride-along confound by dividing it out.
+
+And even pull-through is *correlation*: a lesson can pull through because it was
+genuinely useful, or because the task was easy and any nudge looked right. Counter
+movement alone can never separate "the lesson helped" from "the run would have
+succeeded anyway." Only a run that deliberately did **not** get the memory can — see
+[the north star](#the-north-star-a-withheld-memory-control-arm).
+
+## The optional counter view (advisory only)
+
+Once the immunity check is in place, the counters are a useful *secondary* read — never
+the headline:
+
+- **Pull-through per bucket** — `opened_count / read_count` across `loop::<host>-lessons`.
+  A bucket read often and opened rarely is dead weight to prune, not proof of value.
+- **`/insights`** — the dashboard's Lore Utility grid classifies each lesson
+  (load-bearing / specialist / noise-tax / dormant) from pull-through against an
+  evidence floor. Consult it to find lessons to promote (load-bearing) or retire
+  (noise-tax), not to claim the loop improved a host.
+- **`cited_count`** — when a host cites the lessons it applied (`cited` on the write),
+  a rising `cited_count` on a lesson is *evidence* it is being used. It is evidence,
+  never a denominator: a `0` means "nobody said so", not "unused".
+
+State the confound wherever you report these: raw counters describe supply, not lift.
+
+## Declare the metric at wiring time
+
+Do this at step 6 of the quickstart, not months later when you have forgotten what
+"better" meant:
+
+- **Required:** name the failure signature (the **Applies when** line) whose recurrence
+  you will watch after promotion.
+- **Optional:** name the one bucket pull-through you will glance at, and the interval.
+- Write it into the host's own docs next to the loop's read/write steps, so a future
+  maintainer inherits the definition of "working" instead of re-inventing it.
+
+## The north star: a withheld-memory control arm
+
+The only *rigorous* attribution is a control arm: deterministically bucket a small
+fraction of runs into a **lessons-suppressed** arm (reuse LoreKit's feature-flags
+FNV-1a bucketing on a stable run id), then compare outcome rates — retry count,
+first-try pass, wall-clock — between treated and control. That yields lift with a
+confidence interval instead of a ratio.
+
+This is the aspiration, **not a requirement**, for two honest reasons: it needs product
+infrastructure that does not exist yet (a per-loop lift harness), and deliberately
+withholding memory has a real UX/ethics cost, so it must be opt-in. Treat it as the
+direction of travel; ship the immunity re-challenge today.
+
+## Guards
+
+- **Do not measure a loop you seeded.** Cold-start seeding erases the clean baseline the
+  immunity check reads — see [cold-start-seeding.md](./cold-start-seeding.md). Pick, per
+  loop: run-one value (seed it) OR provable lift (leave it cold).
+- **A flat `seen_count` after promotion is proof only if the loop is still firing.**
+  Confirm the loop is alive first ([loop-health.md](./loop-health.md#is-the-loop-firing));
+  a dead loop also has a flat count, for the wrong reason.
+- **Never gate anything on a counter.** These are proof for a human, not a machine gate.
+  The only mechanical gate is the compiled invariant ([compiled-invariants.md](./compiled-invariants.md)).

package/skill/lorekit-setup/rules/self-improvement-loops.md

@@ -15,6 +15,7 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 
 ## Contents
 
+- [Find where a loop pays off](#find-where-a-loop-pays-off)
 - [When to add a loop (and when not to)](#when-to-add-a-loop-and-when-not-to)
 - [The two tiers](#the-two-tiers)
 - [Conventions](#conventions)
@@ -30,6 +31,41 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 
 ---
 
+## Find where a loop pays off
+
+Do not ask a newcomer to *guess* where memory helps — the best place for a loop is a
+statistical property of the codebase's own history, and the data already knows it. Answer
+"where?" before "how?".
+
+**Start from recurring pain, not from a host you happen to be looking at.** A loop earns
+its keep only where the same class of failure happens more than once. Two ways to surface
+that:
+
+- **From the store, if loops already exist:** `lorekit dedupe` clusters near-duplicate
+  lessons, and `lorekit invariants candidates` ranks clusters by summed `seen_count` ×
+  distinct scopes — literally "how often, in how many places, did this recur." A high-
+  ranked cluster with no dedicated host is a loop waiting to be wired.
+- **From history, on a cold repo:** the same pattern fixed the same way 3+ times, a
+  revert-then-refix chain, a review note left across many PRs, or an existing CI guard —
+  each is a lesson someone already learned. `git log`, `git log --grep=revert`, and the
+  `obligations-map` are the seams. These double as seed sources —
+  [cold-start-seeding.md](./cold-start-seeding.md).
+
+**Then match the host to an archetype** and copy its recipe card rather than wiring from
+scratch:
+
+| The host… | Card |
+| --------- | ---- |
+| edits code, fails in recurring ways | [code-changing-agent](../templates/code-changing-agent.md) |
+| posts durable outputs at a target it revisits | [reviewer-reconcile-host](../templates/reviewer-reconcile-host.md) |
+| is a pipeline that fails in classifiable ways | [multi-step-orchestrator](../templates/multi-step-orchestrator.md) |
+| is a deterministic CI job needing last-run state | [ci-job](../templates/ci-job.md) |
+
+The abstract test in the next section is the fallback when no recurrence data exists yet —
+apply it, but prefer the evidence above when you have it.
+
+---
+
 ## When to add a loop (and when not to)
 
 Add a loop when **all** of these hold:
@@ -71,6 +107,11 @@ across runs** — recurrence is the cheap external signal that the lesson is rea
 not a one-off. This is the episodic → procedural promotion path, with a human
 gate on the slow tier so a single bad run can never rewrite the host.
 
+Both tiers are **read by people as well as agents** — a teammate browsing the
+dashboard, a reviewer asking why a rule exists. That is why a lesson body is
+plain markdown with no hidden payload; see
+[the lesson record](#the-lesson-record).
+
 The fast tier is optional: if LoreKit's `memory.*` tools are not connected, the
 loop is a silent no-op (log one line, continue). The slow tier is just editing
 the host and is unaffected.
@@ -101,44 +142,139 @@ Reserve `branch::` for throwaway notes; a loop normally writes `global` or
 ### The lesson record
 
 A loop lesson is **procedural** ("how to do better next time"), not a fact about
-the user. Keep the machine-read metadata in a `meta:` comment at the top of the
-`value` so the prose stays readable:
+the user. The `value` is **markdown a human reads** — in the dashboard, in a
+SessionStart injection, in another agent's context — and nothing else. Write it
+to this shape:
 
 ```markdown
-<!-- meta: seen_count=1 status=active expires=<ISO 8601, ~90 days out> trigger-context="<concrete signal — file glob, task type, tool, error shape>" -->
+# <one-line takeaway — what to do, not what the lesson is about>
 
-# <one-line lesson title>
+**Applies when:** <concrete signal — file glob, task type, tool name, error shape>
 
-**What failed:** <concrete observable from the run>
+**What happened:** <the concrete observable from the run>
 **Why:** <root cause, if known; "unknown" is allowed>
-**What to do next time:** <prescriptive, actionable, testable instruction>
+**Do this instead:** <prescriptive, actionable, testable instruction>
 **Promotion target:** <the host rule/step this would harden if promoted, or "none">
 ```
 
-`trigger-context` must be **concrete** (globs, task types, tool names, error
-shapes) — never "when it feels relevant" — so the read step can match it
-mechanically. `seen_count`, `status`, and `expires` drive recurrence, promotion,
-and decay.
+`Applies when` must be **concrete** (globs, task types, tool names, error
+shapes) — never "when it feels relevant" — so the read step can match it against
+the current run. It is a visible line, not hidden metadata: the reader deciding
+whether a lesson is theirs needs it first, which is why it sits directly under
+the title.
+
+#### Never put machine metadata in the body
+
+**A lesson body carries no hidden or machine-only payload — no HTML comment, no
+front-matter block, no JSON blob, no `key=value` header.** Every byte of `value`
+must render as prose a person can read. This is not a style preference; a body
+field is the wrong home for each of these on the merits:
+
+| Fact | Where it belongs | Why not the body |
+| ---- | ---------------- | ---------------- |
+| **Recurrence count** | `seen_count`, a store column | `memory_write` sets `seen_count = memories.seen_count + 1` on every overwrite. A count written into prose is a snapshot the writer guessed at and nothing ever updates — stale the first time the lesson recurs, and readers of the real counter never see it |
+| **Expiry** | `ttl_days` on the write (`clear_ttl` to make permanent) | Expiry is enforced against the column by `memory.purge_expired` and the read filters. A date in prose expires nothing |
+| **Status** (`structural`, `promoted`) | a `status::<value>` tag | Tags are first-class and filterable — `memory.list { tags: ["status::structural"] }` finds them. Prose is not queryable |
+| **Owning host / bucket kind** | the `host` and `kind` write fields | Both are first-class, inferred from the `loop::<host>-lessons` tag when omitted, and drive the Explorer's own facets |
+| **Provenance** (repo, branch, commit, PR) | `origin_repo` / `origin_branch` / `origin_commit` / `origin_pr` | First-class, and the dashboard renders them as links |
+| **Trigger** (`stuck-loop`, `command-failure`, …) | the `trigger` write field | Already a facet; restating it in prose adds a line and no information |
+
+An HTML comment is the worst of both worlds: markdown renders it to *nothing*, so
+a human sees a lesson that starts mid-thought, while the fields inside it silently
+disagree with the store's own columns. If a fact has a first-class home, put it
+there and leave it out of the prose entirely.
+
+This rule governs **lesson** bodies. A CI **state record** is a different shape
+on purpose — its whole `value` is a JSON object, authoritative and parsed rather
+than read, with no prose wrapped around it. See
+[ci-state-records.md](./ci-state-records.md).
+
+#### Writing rules
+
+Enforce these on every write, autonomous or not:
+
+- **One lesson per record.** Two takeaways are two keys.
+- **Lead with the takeaway.** The `#` title is the instruction, not the topic —
+  "Pass `--node-modules-dir=none` to `deno check`", not "Notes on deno check".
+- **Bold label, then one short paragraph.** No nesting past one list level, no
+  sub-headings; the whole record is read at a glance or not at all.
+- **Fence every command or snippet**, with a language tag.
+- **Budget ~1,500 characters.** A lesson longer than a screen is a document, and
+  a loop that injects documents crowds out the run it was meant to help. Cut the
+  narrative, keep the instruction.
+- **No run residue** — no transcript excerpts, reasoning traces, session or
+  correlation IDs, timestamps, or "in this run I…" framing. A lesson is written
+  for the *next* run, which has none of that context.
+- **No secrets or PII**, per the privacy pre-flight in the write step.
+
+#### Worked example
+
+❌ **Don't** — a hidden header, a title that names a topic, and a run narrative:
+
+```markdown
+<!-- meta: seen_count=1 status=active expires=2026-12-11 trigger-context="bash: line 5: dash0link: command not found" -->
+# Notes on the Slack tool
+**What failed:** In this run I called `slackSendMessage --args='{ … `dash0link` … }'`
+and got `bash: line 5: dash0link: command not found`, then retried twice with
+different escaping before it worked. Session 4b1c2efe, 2026-09-11.
+```
+
+Everything before the title renders to nothing for a human; `seen_count` and
+`expires` contradict the store the moment the lesson recurs; the title says what
+the lesson is *about* rather than what to do; and the run residue is dead weight
+in every future context window.
+
+✅ **Do** — the same lesson, all metadata in its own field:
+
+````markdown
+# Send Slack messages via a heredoc, not inline `--args='…'`
+
+**Applies when:** shelling out to `slackSendMessage` with text interpolated from
+an external source (ticket titles, PR titles) that may contain backticks or apostrophes.
+
+**What happened:** Inline `--args='{ … }'` failed with `bash: dash0link: command not found` —
+the shell expanded backticks in the JSON, and an apostrophe closed the quoted argument early.
+**Why:** Single quotes do not protect the string once the outer shell re-processes it.
+**Do this instead:** Pass the JSON through a quoted heredoc, which needs no escaping:
+
+```bash
+tools invoke slack.slackSendMessage --args="$(cat <<'ENDJSON'
+{ "text": "…" }
+ENDJSON
+)"
+```
+
+**Promotion target:** the automation prompt's message-building step.
+````
+
+Written with `tags: ["loop::<host>-lessons", "source::command-failure"]`,
+`trigger: "command-failure"`, and `ttl_days: 90` — so the recurrence count, the
+expiry, the owning host and the trigger are all queryable, and the body is
+readable start to finish.
 
 ---
 
 ## Read step (start of every run)
 
-Read narrow-to-broad, filtered by the bucket tag, and merge:
+Read narrow-to-broad, filtered by the bucket tag, and merge — but **capped**. A loop
+injects at most a small N (`limit: 5` per scope by default) into a run. This is a wiring
+precondition, not a tuning knob: many uncapped loops on the same scopes tax every
+session's context until agents learn to ignore injected lore entirely. Raise N only with
+a reason.
 
 ```text
-memory.list { scope: "repo::{owner}/{repo}", tags: ["loop::<host>-lessons"], limit: 50 }   # skips silently if memory.* not connected
-memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 50 }
+memory.list { scope: "repo::{owner}/{repo}", tags: ["loop::<host>-lessons"], limit: 5 }   # skips silently if memory.* not connected
+memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 5 }
 # when the run names a subsystem / error, add a search:
-memory.search { q: "<keywords>", scopes: ["repo::{owner}/*", "global"], limit: 10 }
+memory.search { q: "<keywords>", scopes: ["repo::{owner}/*", "global"], limit: 5 }
 ```
 
 Then:
 
-1. Match each lesson's `trigger-context` against the current run. Consider only
-   matches. **Skip any lesson whose `expires` is in the past** — treat it as
-   stale.
-2. Apply each matching *"What to do next time"* as a **consideration**, not a
+1. Match each lesson's **Applies when** line against the current run. Consider
+   only matches. Expired lessons do not come back — the store's own TTL drops
+   them, so the read never has to filter on a date in the prose.
+2. Apply each matching **Do this instead** line as a **consideration**, not a
    command — it biases the run unless it conflicts with the user's stated intent
    or a task-specific constraint. On conflict, the user's intent wins; surface it.
 3. On a `repo::` vs `global` collision, the `repo::` lesson wins (closer scope).
@@ -161,23 +297,31 @@ caught something, a near-miss, a guess that paid off. Not on smooth successes.
    memory.search { q: "<key words of the lesson>", scopes: ["repo::{owner}/{repo}", "global"], limit: 10 }
    ```
 
-3. **Write** to the classified scope:
+3. **Write** to the classified scope, putting every fact in its own field and
+   nothing but prose in `value`:
 
    ```text
    memory.write {
-     scope: "<global | repo::{owner}/{repo}>",
-     key:   "<host>-lessons::<slug>",
-     value: "<the lesson body above>",
-     tags:  ["loop::<host>-lessons", "source::<trigger>"],
-     trigger: "<stuck-loop | command-failure | gotcha | near-miss | assumption-wrong | paid-off | manual>"
+     scope:     "<global | repo::{owner}/{repo}>",
+     key:       "<host>-lessons::<slug>",
+     value:     "<the markdown lesson body above — no hidden blocks>",
+     tags:      ["loop::<host>-lessons", "source::<trigger>"],   # + "status::structural" when it is
+     trigger:   "<stuck-loop | command-failure | gotcha | near-miss | assumption-wrong | paid-off | manual>",
+     ttl_days:  90
    }
    ```
 
-Same `scope` + `key` overwrites in place. **A recurrence resolves to an UPDATE
-that increments `seen_count` by 1 and refreshes `expires`** — that is what makes
-recurrence countable and drives promotion. If a lesson you applied at the start
-of the run worked (the failure did not recur), still write the UPDATE:
-successful application is recurrence evidence.
+   `host` and `kind` are inferred from the `loop::<host>-lessons` tag; pass them
+   explicitly only when the tag does not carry them. Add the `origin_*` fields
+   when the run knows them.
+
+Same `scope` + `key` overwrites in place. **A recurrence resolves to an UPDATE:
+the store increments `seen_count` by 1 for you, and re-passing `ttl_days`
+refreshes the expiry** — that is what makes recurrence countable and drives
+promotion. Never hand-write a count into the body to track this; the column is
+the only copy that stays true. If a lesson you applied at the start of the run
+worked (the failure did not recur), still write the UPDATE: successful
+application is recurrence evidence.
 
 The privacy pre-flight is never skipped, autonomous or not: a candidate lesson
 containing a secret, token, credential, or PII is **dropped, not written**. The
@@ -381,8 +525,9 @@ hotspots during review), and every code-changing host — `aw`, `implement-sugge
 
 After a read or write, a lesson is **promotion-eligible** when either:
 
-- `seen_count >= 3` — the same failure recurred across at least three runs, or
-- it is tagged `status=structural` because it reflects a design gap, not a
+- `seen_count >= 3` — the same failure recurred across at least three runs (read
+  the store's column, never a number written into the body), or
+- it carries the `status::structural` tag because it reflects a design gap, not a
   one-off.
 
 For an eligible lesson, **surface a one-line suggestion — never act silently**:
@@ -394,8 +539,8 @@ The promotion target follows the lesson's scope: a `global` lesson hardens the
 **host's own source** (every user of the host benefits); a `repo::` lesson
 hardens the **repo's own rules / docs** (every teammate in that repo benefits).
 Promotion is a normal, human-reviewed edit — LoreKit does not apply it. After a
-successful promotion, write an UPDATE setting `status=promoted` so the lesson
-stops re-suggesting and stands as an audit trail of why the rule exists.
+successful promotion, write an UPDATE adding the `status::promoted` tag so the
+lesson stops re-suggesting and stands as an audit trail of why the rule exists.
 
 A recurring lesson can be promoted a second time, past the prose rule above,
 into a **compiled invariant** — a declarative, mechanically-checked assertion
@@ -420,9 +565,10 @@ guards are what make the loop safe:
    run; it can never silently disable a gate, skip a step, or change a limit. The
    only path from a lesson to changed behavior is the human-reviewed slow tier.
 2. **Recurrence gates promotion, not a single run** (`seen_count >= 3`, or an
-   explicit `status=structural` marker in the lesson's `meta:` comment).
-3. **Every lesson expires** (default ~90 days from last sighting; the read step
-   ignores expired lessons, so stale beliefs decay instead of entrenching).
+   explicit `status::structural` tag on the lesson).
+3. **Every lesson expires** — `ttl_days: 90` on the write, refreshed on each
+   recurrence, so stale beliefs decay instead of entrenching. The store enforces
+   this; an expiry stated only in prose is decoration.
 4. **Contradiction is surfaced, not silently overwritten** — the dedup search
    finds the prior lesson; a genuine reversal is a reviewed decision.
 5. **The privacy pre-flight is never bypassed** — secrets / PII are dropped, not
@@ -436,13 +582,14 @@ To add a loop to a host called `<host>`:
 
 - [ ] Pick the bucket: tag `loop::<host>-lessons`, key `<host>-lessons::<slug>`.
 - [ ] Add the **read step** at the start of the host's run (narrow-to-broad
-      `memory.list` filtered by the tag; apply matches as considerations; skip
-      expired).
+      `memory.list` filtered by the tag; apply matches as considerations).
 - [ ] Add the **write step** at the host's existing failure / end-of-run points
-      (classify scope, `memory.search` to dedup, `memory.write`). No new
-      reflection stage — hook the points the host already detects.
+      (classify scope, `memory.search` to dedup, `memory.write` with `ttl_days`).
+      No new reflection stage — hook the points the host already detects.
+- [ ] State the **body contract** in the host's own write step: markdown to the
+      shape above, no hidden blocks, every store-backed fact in its own field.
 - [ ] Add the **promotion suggestion** when a read/written lesson hits
-      `seen_count >= 3` or `status=structural`.
+      `seen_count >= 3` or carries `status::structural`.
 - [ ] State the **entrenchment guards** so a future maintainer does not "optimize
       them away".
 - [ ] Confirm the loop **degrades silently** when `memory.*` is not connected.
@@ -450,6 +597,14 @@ To add a loop to a host called `<host>`:
       read** at its plan/apply seam (match `hotspot::<path>` /
       `knowledge::<symbol>@<path>` to the files it will change). If it **verifies**
       a structural fact, wire the **write** behind that section's contract.
+- [ ] Set the **injection cap** (`limit: 5` per scope by default) on the read step —
+      a wiring precondition, not a tuning knob.
+- [ ] Decide **seeding**: value on run one ([cold-start-seeding.md](./cold-start-seeding.md),
+      a handful, curated) **or** provable lift (leave it cold) — never both.
+- [ ] Declare the **proof** — the immunity re-challenge whose failure signature you will
+      watch after promotion ([proving-improvement.md](./proving-improvement.md)).
+- [ ] Add the **health checks** — a canary, the write-time matchability check, and the
+      quarantine-not-delete rollback ([loop-health.md](./loop-health.md)).
 
 ---