@lorekit/cli 1.68.0 → 1.70.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.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-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

@@ -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,23 +39,87 @@ 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.
+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:
 
-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 host is… | Wants | Read |
+| ------------ | ----- | ---- |
+| A **model-driven** skill, agent, or workflow that fails in recurring, classifiable ways | Prose **lessons** — advisory, recurrence-gated, promotable into rules | [rules/self-improvement-loops.md](./rules/self-improvement-loops.md) |
+| A **deterministic job** — a GitHub Actions workflow, a cron script, a release pipeline — that needs last-run state | JSON **state records** — authoritative, parsed, one key per fact | [rules/ci-state-records.md](./rules/ci-state-records.md) |
+| A recurring lesson whose failure mode is judgement-free and checkable against an independent source of truth | A **compiled invariant** — a declarative entry a CI gate enforces mechanically, never advisory once `gating` | [rules/compiled-invariants.md](./rules/compiled-invariants.md) |
+
+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*.
 
 ## 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.
+The runtime loop is two tiers, fast and slow; a third, rarer rung sits past promotion.
 
 | Rung | Mechanism | Changes behavior? | Advisory or enforced? |
 | ---- | --------- | ----------------- | ---------------------- |
@@ -65,66 +127,65 @@ mechanically-checked rule instead of text a reader has to notice.
 | **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 is marked `status=structural` 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
+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
+
+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 |
+| ---- | ---------------- |
+| 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; 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.
 
-Two kinds of host want memory, and they want a different record. Decide which
-before reading further:
-
-| The host is… | Wants | Read |
-| ------------ | ----- | ---- |
-| A **model-driven** skill, agent, or workflow that fails in recurring, classifiable ways | Prose **lessons** — advisory, recurrence-gated, promotable into rules | [rules/self-improvement-loops.md](./rules/self-improvement-loops.md) |
-| A **deterministic job** — a GitHub Actions workflow, a cron script, a release pipeline — that needs last-run state | JSON **state records** — authoritative, parsed, one key per fact | [rules/ci-state-records.md](./rules/ci-state-records.md) |
-| A recurring lesson whose failure mode is judgement-free and checkable against an independent source of truth | A **compiled invariant** — a declarative entry a CI gate enforces mechanically, never advisory once `gating` | [rules/compiled-invariants.md](./rules/compiled-invariants.md) |
-
-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 shared codebase-knowledge layer (automatic cross-loop synergy)
 
-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.
+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).
 
-## The shared codebase-knowledge layer (automatic cross-loop synergy)
+## Connectivity
 
-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 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/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/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/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.