@lorekit/cli 1.68.0 → 1.69.0

package/README.md

@@ -277,6 +277,25 @@ missing. It exits **non-zero** when the key is found in no readable store, so it
 fits scripts. `--json` emits the full normalized record(s) and which store each
 came from. Both a scope and a key are required (else a usage error).
 
+#### Batch mode: several references in one call
+
+Pass **two or more** references and `show` fetches all of them in one pass
+instead of one invocation per lesson:
+
+```bash
+lorekit show global::prefer-guard-clauses repo::acme/widget::build-flags --json
+```
+
+Each positional must itself parse as a complete `<scope>::<key>` reference —
+that is what tells this apart from the existing `show <scope> <key>`
+two-positional form, whose first positional is a **bare** scope with no `::`.
+Results are reported in the same order the references were given, and
+`--json` emits `{ "results": [{ "scope", "key", "offline", "remote", "diverged" }, …] }`
+instead of the single-reference top-level shape. The remote half of a batch is
+ONE round trip (`POST /memories/read`), not one request per reference; the
+offline half still resolves each reference through the two-tier store, so a
+project-tier lesson still shadows a same-key home-tier one.
+
 ### Addressing a memory: `<scope::key>`
 
 `show`, `write` and `link` all take a memory the same way, and the single-token
@@ -523,10 +542,11 @@ lorekit invariants candidates --scope repo::owner/repo
 ```
 
 A cluster is a candidate when the **summed `seen_count`** across its members
-is at least `--min-seen-count` (default `3`), or any member's own
-`<!-- meta: seen_count=… status=… trigger-context="…" -->` comment (the
-convention documented in the `lorekit-setup` skill's
-`self-improvement-loops.md`) already declares a non-`"active"` status.
+is at least `--min-seen-count` (default `3`), or any member already declares a
+non-`"active"` status. Status is read from a `status::<value>` **tag** — the
+canonical home, per the `lorekit-setup` skill's `self-improvement-loops.md` —
+falling back to a legacy `<!-- meta: … status=… -->` body comment for lessons
+written before tags were the convention; the tag wins when both are present.
 Candidates are ranked by (summed `seen_count` × distinct scopes), descending.
 **For each candidate it prints every memory the merge would collapse** —
 that list is the whole point of the command.
@@ -536,10 +556,11 @@ whose members already resolve to a named recurrence class is flagged as a
 stronger case ("this should join an existing invariant") than a merely
 similar one ("this might be a new class").
 
-It deliberately does **not** classify a `trigger-context` into a
-glob/command/error-shape — that judgment is the human step the compile
-pipeline's "never auto-compile, never auto-gate" rule protects, so the raw
-string is printed, never interpreted — and it does **not** know about
+It deliberately does **not** classify a member's applicability signal — its
+visible `**Applies when:**` body line, or a legacy `trigger-context` meta
+field — into a glob/command/error-shape. That judgment is the human step the
+compile pipeline's "never auto-compile, never auto-gate" rule protects, so the
+raw string is printed, never interpreted — and it does **not** know about
 `compiled_to` (no such field exists yet, so an already-compiled candidate can
 still surface here — a known, named gap, not a silent omission).
 

package/package.json

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

package/skill/lorekit-memory/SKILL.md

@@ -120,9 +120,9 @@ Full resolution rules: [references/scope-resolution.md](./references/scope-resol
 
 | Tool | Use | Token |
 |------|-----|-------|
-| `memory.list` | List lessons for one scope (newest first, tag filter) | read |
+| `memory.list` | List lessons for one scope (newest first, tag filter). `scope` is optional — omit it to list across every scope you can see | read |
 | `memory.search` | Full-text search across scopes (supports `repo::owner/*`) | read |
-| `memory.read` | Read one lesson by scope + key | read |
+| `memory.read` | Read one lesson by key (`scope` optional — see below) — or several at once via `refs: ["scope::key", …]` (one round trip, up to 32) | read |
 | `memory.write` | Store or update a lesson (same scope+key updates in place) | read+write |
 
 Write tools need write permission (`lk_rw_*` or `lk_wo_*`); read tools need read
@@ -130,6 +130,24 @@ permission (`lk_rw_*` or `lk_ro_*`). A read-only token cannot write and a
 write-only token cannot read — if a call fails with an authorization error,
 report it and move on; do not retry.
 
+Holding only a bare key, with no scope? Call `memory.read { key }` without a
+`scope`. It resolves across every scope you can see, preferring the most
+specific — `project`, then `branch`, then `repo`, then `global` — and the
+response's `scope` field names the one that answered. If the key also exists
+elsewhere, `other_scopes` lists those: that is your cue to pass an explicit
+`scope` next time, because only you know which one you meant. An omitted scope
+does NOT mean `global`. The same applies to `memory.list` and
+`memory.list_archived`, which simply list across everything instead of
+resolving to one winner.
+
+Already know the exact `scope::key` refs you need — from a prior `memory.list`
+or `memory.search`, or from citations another lesson names — and need more than
+one? Pass them all as `memory.read`'s `refs` array instead of one call per
+lesson. Each ref resolves independently: an unresolved one lands in the
+response's `missing` list rather than failing the whole call, and matching is
+against the **verbatim stored scope** (no case-folding), unlike a single
+`scope`/`key` read.
+
 Every lesson this skill writes carries the tag `skill::lorekit-memory` plus a
 `source::<trigger>` tag (for example `source::stuck-loop`) so lessons are
 easy to find and audit later.

package/skill/lorekit-memory/references/scope-resolution.md

@@ -37,6 +37,27 @@ Query most specific first, then merge; more specific scopes win on key collision
 branch::{owner}/{repo}::{branch}   →   repo::{owner}/{repo}   →   project::{name}   →   global
 ```
 
+## Reading without a scope
+
+`memory.read`, `memory.list` and `memory.list_archived` all take an **optional**
+`scope`. Omitting it does not mean `global` — it means "every scope I can see".
+
+`memory.read { key }` resolves the key across all of them and returns ONE
+lesson, preferring the most specific scope type:
+
+```text
+project::{name}   →   branch::{owner}/{repo}::{branch}   →   repo::{owner}/{repo}   →   global
+```
+
+(Same precedence as the read order above, ranked by scope TYPE rather than by
+your own scopes — a hosted call has no working directory to derive them from.)
+Ties within a type break by most-recently-updated. The response's `scope` names
+the scope that answered; `other_scopes`, when present, lists the ones it
+shadowed — pass an explicit `scope` next time if that is not the one you meant.
+
+`memory.list` / `memory.list_archived` simply widen instead: every entry carries
+its own `scope`, and nothing is resolved away.
+
 ## Write scope (retrospective)
 
 Use the narrowest scope that correctly describes where the lesson applies:
@@ -54,7 +75,8 @@ Use the narrowest scope that correctly describes where the lesson applies:
 ```
 
 Wildcards work **only** in `memory.search` — not in `memory.list`,
-`memory.read`, or `memory.write`.
+`memory.read`, or `memory.write`. On the two read tools, omitting `scope`
+entirely (above) is the way to reach past a single scope.
 
 ## Validation rules
 

package/skill/lorekit-setup/SKILL.md

@@ -66,7 +66,7 @@ mechanically-checked rule instead of text a reader has to notice.
 | **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 is marked `status=structural` becomes promotion-eligible. Entrenchment guards
+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.
@@ -93,6 +93,30 @@ It covers: when to add a loop (and when not to), the bucket convention (tag
 read/write steps, the promotion gate, the entrenchment guards, a wiring
 checklist, and an interactive setup flow.
 
+### 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:
+
+| Fact | Field, not prose |
+| ---- | ---------------- |
+| Recurrence | `seen_count` — the store increments it on every overwrite |
+| Expiry | `ttl_days` (`clear_ttl` to make permanent) |
+| Status (`structural` / `promoted`) | a `status::<value>` tag |
+| Owning host, bucket kind | `host`, `kind` |
+| 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).
+
 ## The shared codebase-knowledge layer (automatic cross-loop synergy)
 
 A per-host lessons bucket is private to one host. There is also **one shared

package/skill/lorekit-setup/rules/ci-state-records.md

@@ -58,7 +58,7 @@ this rule should say so out loud rather than sell the store.
 |  | Lesson (`self-improvement-loops.md`) | CI state record (this file) |
 | --- | --- | --- |
 | Author | a model, at the end of a run | a script, deterministically |
-| Value | prose + a `meta:` comment | JSON (an object, not a bare scalar) |
+| Value | markdown prose only — metadata lives in the store's own fields | JSON (an object, not a bare scalar) |
 | How a reader uses it | **advisory** — a consideration that can be overridden | **authoritative** — parsed and branched on |
 | Recurrence / promotion | yes (`seen_count`, human-gated hardening) | n/a — nothing is inferred, so nothing needs gating |
 | Entrenchment risk | high — the reason those guards exist | none; the risks are cardinality and secrets instead |

package/skill/lorekit-setup/rules/compiled-invariants.md

@@ -34,9 +34,9 @@ A lesson is a compile candidate only if **all four** hold:
 1. **Trigger detectable without judgement.** The condition that should fire the
    check can be recognized from a file path, a diff shape, or another mechanical
    signal — not "whether this edit is the kind that matters," which needs a
-   reader's judgement. This is exactly what the existing "trigger-context must be
-   concrete" requirement in the lessons loop exists for: a lesson with a vague
-   trigger-context was never going to compile, so demanding concreteness at
+   reader's judgement. This is exactly what the existing "**Applies when** must
+   be concrete" requirement in the lessons loop exists for: a lesson with a vague
+   applicability signal was never going to compile, so demanding concreteness at
    write time is what keeps the door open later.
 2. **Assertion statable as must-remain-true.** The rule has to be expressible as
    an invariant ("if A changed, B must also be in the changed set"), not a
@@ -114,8 +114,9 @@ A read-only survey over the memory store. It reuses `dedupe`'s Jaccard clusterin
 to find near-duplicate lessons, then ranks the resulting clusters by
 `(summed seen_count × distinct scopes)`, descending. A cluster is worth
 reporting when the summed `seen_count` across its members is at least
-`--min-seen-count` (default 3), or any member's `meta` comment already declares a
-non-`active` status. For each candidate it prints every memory the merge would
+`--min-seen-count` (default 3), or any member already declares a non-`active`
+status — read from a `status::<value>` tag, falling back to a legacy `meta`
+comment for lessons written before tags were the convention. For each candidate it prints every memory the merge would
 collapse — deliberately the default view, not hidden behind `--verbose`, because
 that list *is* the point of the command: a human decides from it whether the
 cluster deserves a hand-written entry.
@@ -127,9 +128,9 @@ you to notice by hand.
 
 Two things it deliberately does **not** do, on purpose:
 
-- **It does not classify trigger-contexts.** A lesson's raw `trigger-context`
-  string, when present, is printed verbatim — never interpreted into a
-  glob/command/error-shape. Turning "parses into a detectable trigger" from a
+- **It does not classify applicability signals.** A lesson's raw signal
+  (its **Applies when** line, or a legacy `trigger-context` meta field) is
+  printed verbatim — never interpreted into a glob/command/error-shape. Turning "parses into a detectable trigger" from a
   string into an actual predicate is the human step the compile pipeline
   protects; automating it would be exactly the "auto-compile" this pipeline
   refuses to do.

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

@@ -71,6 +71,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,24 +106,115 @@ 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.
 
 ---
 
@@ -135,10 +231,10 @@ memory.search { q: "<keywords>", scopes: ["repo::{owner}/*", "global"], limit: 1
 
 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 +257,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 +485,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 +499,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 +525,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 +542,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.

package/src/commands/invariants.mjs

@@ -14,15 +14,16 @@
 //
 // Criteria (pure scoring in `../shared/candidates-pure.mjs`):
 //   - summed seen_count across a cluster's members >= --min-seen-count
-//     (default 3), OR any member's `<!-- meta: ... status=... -->` comment
-//     already declares a non-"active" status
+//     (default 3), OR any member already declares a non-"active" status —
+//     a `status::<value>` tag, or a legacy `<!-- meta: ... status=... -->`
+//     comment for lessons written before tags were the convention
 //   - ranked by (summed seen_count × distinct scopes), descending
 //
 // What this deliberately does NOT do:
-//   - classify a trigger-context into a glob/command/error-shape. The raw
-//     `trigger-context` string (when a lesson's meta comment carries one) is
-//     printed verbatim, never interpreted — "parses into a detectable
-//     trigger" is the human step the compile pipeline protects.
+//   - classify an applicability signal into a glob/command/error-shape. The raw
+//     string (a lesson's `**Applies when:**` line, or a legacy meta comment's
+//     `trigger-context`) is printed verbatim, never interpreted — "parses into
+//     a detectable trigger" is the human step the compile pipeline protects.
 //   - check `compiled_to`. No such field exists yet (no schema, no server
 //     support — see the kickoff's Open Questions), so a candidate already
 //     compiled into an obligations-map.mjs entry can still surface here. A
@@ -150,7 +151,13 @@ function buildCandidates(entries, { threshold, minSeenCount }) {
     ...cl,
     members: cl.members.map((m) => {
       const raw = byAddress.get(`${m.scope}::${m.key}`);
-      return { scope: m.scope, key: m.key, seenCount: seenCountOf(raw), value: raw?.value ?? '' };
+      return {
+        scope: m.scope,
+        key: m.key,
+        seenCount: seenCountOf(raw),
+        value: raw?.value ?? '',
+        tags: Array.isArray(raw?.tags) ? raw.tags : [],
+      };
     }),
   }));
   return rankCandidates(clusters, { minSeenCount, resolveClass: resolveRecurrenceClass });
@@ -221,7 +228,7 @@ async function candidates(args) {
     heading('LoreKit invariants candidates');
     log(`  project: ${c.dim(root)}`);
     log(`  scopes:  ${scopes.join('  →  ')}`);
-    log(`  ${c.dim(`criteria: summed seen_count >= ${minSeenCount}, or a member's meta status is non-"active"`)}`);
+    log(`  ${c.dim(`criteria: summed seen_count >= ${minSeenCount}, or a member's status is non-"active"`)}`);
 
     if (offlineSection.available && offlineSection.popCapped) {
       log(`  ${c.yellow('!')} population cap (${POP_CAP}) reached for Offline — results are partial. Narrow with --key-prefix, --since, or --max.`);
@@ -281,8 +288,8 @@ function renderSection(header, section) {
     }
     for (const m of cand.members) {
       const fields = [`seen_count=${m.seenCount}`];
-      if (m.meta.status) fields.push(`status=${m.meta.status}`);
-      if (m.meta['trigger-context']) fields.push(`trigger-context=${JSON.stringify(m.meta['trigger-context'])}`);
+      if (m.status) fields.push(`status=${m.status}`);
+      if (m.appliesWhen) fields.push(`applies-when=${JSON.stringify(m.appliesWhen)}`);
       log(`    ${c.cyan('-')} ${m.scope}::${m.key}  ${c.dim(`(${fields.join(', ')})`)}`);
     }
   }