@lorekit/cli 1.69.0 → 1.71.0

package/README.md

@@ -210,6 +210,27 @@ itself:
 A revoked token is a **failure**, not a warning: fix it by creating a new token
 and running `lorekit install --force`, which offers to replace the stored one.
 
+### `lorekit update`
+
+Offline refresh of the bundled skills (and their hook command string) to the
+version shipped with the running CLI — the fix `doctor`'s outdated-skill
+warning and the SessionStart drift nudge (`updates.notify`) both point at.
+Fully offline: the shipped skill source travels in the same npm tarball as
+this CLI, so "installed vs shipped" is a filesystem version compare, never a
+network call.
+
+```bash
+lorekit update            # refresh every scope that already has an install
+lorekit update --check    # dry run: report drift, write nothing
+lorekit update --project  # only the project (.claude/skills) install
+lorekit update --global   # only the global (~/.claude/skills) install
+```
+
+`update` never CREATES a fresh install — that stays `install`'s job, so a
+scope with nothing installed is reported and left alone. Refreshing prunes
+any file the shipped skill no longer ships before re-copying, so a
+dropped rule file doesn't silently outlive the version that removed it.
+
 ### `lorekit list` (alias `ls`)
 
 Shows the lessons that apply to **where you are** — the scopes `deriveScope`
@@ -1110,8 +1131,8 @@ also returns their headroom against the plan's memory cap.
 | Flag | Meaning |
 |------|---------|
 | `-d, --dir <path>` | Target project root (default: cwd) |
-| `--project` | Install into this repo: `.claude/skills` + `.mcp.json` (`install`; default) |
-| `--global` | Install for every project: `~/.claude/skills` + `~/.claude.json` (`install`) |
+| `--project` | Install into this repo: `.claude/skills` + `.mcp.json` (`install`; default). Narrows to the project scope (`update`) |
+| `--global` | Install for every project: `~/.claude/skills` + `~/.claude.json` (`install`). Narrows to the global scope (`update`) |
 | `-e, --endpoint <url>` | LoreKit MCP endpoint |
 | `-t, --token <token>` | LoreKit token |
 | `--mode <mode>` | Memory mode override for `doctor`: `off` / `local` / `remote` |
@@ -1125,6 +1146,7 @@ also returns their headroom against the plan's memory cap.
 | `--mcp-json` | Also write a committable project `.mcp.json` (auth via `${LOREKIT_TOKEN}`, no embedded token) for Claude Code on the web (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
+| `--check` | Dry run: report skill-install drift without writing anything (`update`) |
 | `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `obligations` / `invariants candidates` / `link` / `purge` / `purge-expired`) |
 | `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory. On `show` / `write` it **names** the scope, overriding the positional |
 | `--key <key>` | Name the key outright (`show` / `write` / `link`) — the way to address a key that itself contains `::` |

package/bin/lorekit.mjs

@@ -39,6 +39,11 @@ ${c.bold('Commands')}
               other servers, hooks, and settings are left untouched. Prompts
               project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, remote connectivity, token, and scope.
+  update      Offline refresh of the bundled skills (and their hook command
+              string) to the version shipped with the running CLI — the fix
+              for doctor's outdated-skill warning. Never creates a fresh
+              install (that's \`install\`'s job); --project / --global narrow
+              to one scope; --check reports drift without writing anything.
   list (ls)   List the memories that apply to the current directory, split into
               an Offline section (local .lorekit/ + ~/.lorekit/) and a Remote
               section (the hosted LoreKit API). Groups by scope (project/branch/repo/global).
@@ -169,6 +174,7 @@ ${c.bold('Options')}
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
       --telemetry         Verify the OTLP export credential works (doctor)
+      --check             Report drift without writing anything (update)
       --adapter <name>    Host framework for hook: claude | cursor | codex
       --event <name>      Host hook event (else read from stdin payload)
   -h, --help              Show this help
@@ -193,6 +199,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli install --global    # set up memory for every project (~/.claude)
   npx @lorekit/cli uninstall --global  # tear that global setup back down
   npx @lorekit/cli doctor --deep
+  npx @lorekit/cli update --check      # report outdated skills without writing
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
   npx @lorekit/cli migrate --from .lorekit --to remote --yes  # push local lore up
@@ -302,6 +309,32 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli doctor --telemetry
   npx @lorekit/cli doctor --mode local
+`,
+  update: `${c.bold('lorekit update')} — offline refresh of the bundled skills to the shipped version
+
+${c.bold('Usage')}
+  npx @lorekit/cli update [options]
+
+Re-copies every bundled skill (force) into whichever scope(s) already have an
+install, and refreshes that scope's hook command string — the same skill-copy
+path and hook-command call \`install --force\` uses, so the two can never
+disagree on what "installing a skill" means. Fully offline: the shipped skill
+source travels in the same npm tarball as this running CLI, so "installed vs
+shipped" is a filesystem version compare, not a network call. Never creates a
+fresh install — that's \`install\`'s job — so a scope with nothing installed is
+reported and left alone.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --project           Only refresh this project's install (.claude/skills)
+      --global            Only refresh the global install (~/.claude/skills)
+      --check             Dry run: report drift (installed vs shipped version
+                          per skill) and write nothing
+
+${c.bold('Examples')}
+  npx @lorekit/cli update
+  npx @lorekit/cli update --check
+  npx @lorekit/cli update --global
 `,
   list: `${c.bold('lorekit list')} — list the memories that apply to the current directory ${c.dim('(alias: ls)')}
 
@@ -1090,6 +1123,8 @@ const KNOWN_FLAGS = [
   'clear-max-opened-count', 'off',
   // `obligations`
   'files', 'strict', 'strict-all',
+  // `update`
+  'check',
 ];
 
 async function main() {
@@ -1102,7 +1137,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'clear-max-opened-count', 'strict', 'strict-all'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'clear-max-opened-count', 'strict', 'strict-all', 'check'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/skill/lorekit-groom/SKILL.md

@@ -18,7 +18,7 @@ argument-hint: '[scope-hint]'
 license: MIT
 metadata:
   author: mthines
-  version: '1.0.0'
+  version: '1.1.0'
   workflow_type: shared-memory-grooming-and-consolidation
   tags:
     - lorekit

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

@@ -17,7 +17,7 @@ argument-hint: '[read|write] [scope-hint or lesson]'
 license: MIT
 metadata:
   author: mthines
-  version: '1.0.0'
+  version: '1.1.0'
   workflow_type: shared-memory-intake-and-retrospective
   tags:
     - lorekit

package/skill/lorekit-setup/SKILL.md

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

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

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