@lorekit/cli 1.67.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.67.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-groom/rules/grooming-pass.md

@@ -175,3 +175,13 @@ new count. Then either move to the next scope or close out the pass.
 - **Someone else's lesson deserves more caution.** A lesson tagged from another
   agent or a teammate is not automatically yours to delete — when in doubt,
   archive rather than hard-delete, and flag it in the plan.
+- **`codebase-knowledge` is durable structure, not an audit log.** The shared
+  `codebase-knowledge` bucket (tag `codebase-knowledge`, `knowledge::<symbol>@<path>`
+  and `hotspot::<path>` keys — see the `lorekit-setup` skill) is a live,
+  multi-loop signal store: every LoreKit loop in the repo both reads and feeds it.
+  Groom it like a signal store, never like the audit-log prose it superficially
+  resembles. Lint its structure and dedupe genuine key collisions, but do **not**
+  mass-archive by age or volume, and do **not** re-key a `knowledge::<symbol>@<path>`
+  entry off its structural key — that key is the join a reader matches against.
+  A stale fact carries `verified_at_sha`; prefer letting its TTL expire or the
+  owning loop overwrite it over hand-removing it.

package/skill/lorekit-memory/SKILL.md

@@ -75,7 +75,12 @@ Read at the moments where prior lessons change what you do:
 
 Follow [rules/intake.md](./rules/intake.md).
 The short version: resolve the current scope, list lessons narrow-to-broad,
-and treat matches as *considerations*, not commands.
+and treat matches as *considerations*, not commands. When a run is about to
+change code, intake step 6 reads the standard shared **`codebase-knowledge`**
+bucket — the cross-loop `hotspot::<path>` / `knowledge::<symbol>@<path>` record
+for the files this run will touch, matched by `symbol@path`. A run that verifies
+a structural fact contributes it back, so the layer compounds across every
+LoreKit loop in the repo (contract in the `lorekit-setup` skill).
 
 ## When to write (retrospective)
 
@@ -115,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
@@ -125,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-memory/rules/intake.md

@@ -59,3 +59,44 @@ If lessons matched, note them in one or two lines before proceeding
 ("LoreKit: 2 relevant lessons — worktree naming, migration order").
 If nothing matched, say nothing and continue.
 If the MCP tools are not connected, note it once and continue without them.
+
+## 6. When the run will change code — read the shared codebase-knowledge
+
+Steps 1–4 read **your own** bucket. When this run is about to change code, do one
+more read — not optional, it is how the cross-loop synergy reaches you: the shared
+**`codebase-knowledge`** bucket. This is the repo-scoped, cross-loop record of what
+the codebase has taught every LoreKit loop that touched it
+(`knowledge::<symbol>@<path>` facts, `hotspot::<path>` counters). Its keys are
+**structural** (`symbol@path`, a file path) rather than prose, so you match them
+against the concrete files and symbols this run will touch and pull only the
+records that apply. Read it for exactly the files you will change:
+
+```text
+memory.list { scope: "repo::{owner}/{repo}", tags: ["codebase-knowledge"], limit: 100 }
+# keep only hotspot::<path> / knowledge::<symbol>@<path> whose <path> (and <symbol>)
+# the current change will actually touch — a known regression hotspot or a
+# repeatedly-flagged symbol is then planned with that history in hand.
+```
+
+If this run **verifies** a structural fact about a symbol or file (a consumer
+count you swept, an invariant you confirmed, a defect you fixed at a SHA),
+contribute it back so the next code-changer benefits — write it to
+`codebase-knowledge` under the write contract in the `lorekit-setup` skill,
+`rules/self-improvement-loops.md § Shared codebase-knowledge`. The layer fills
+because its readers also feed it.
+
+Four rules make this safe, and they are non-negotiable:
+
+- Match **structurally and narrowly** — the paths/symbols of this run, never the
+  whole bucket.
+- It **raises care, never lowers a bar** — plan more coverage on a hotspot; an
+  absent record is not evidence of safety.
+- A fact may be **stale** (it carries the writer's `verified_at_sha`) — treat it
+  as a consideration and re-verify against the code.
+- **Read-only.** Never write another host's bucket; write ownership stays with
+  its one owner.
+
+Do **not** cross-read another host's `loop::<host>-lessons` — those are prose
+advice with no structural key to match on. The full contract and when to wire a
+cross-read into a host is the `lorekit-setup` skill,
+`rules/self-improvement-loops.md § Cross-bucket reads (targeted, read-only)`.

package/skill/lorekit-memory/rules/retrospective.md

@@ -14,6 +14,13 @@ Ask the 30-second question:
 If no, stop — write nothing. Empty retrospectives are skipped.
 If yes, continue.
 
+> A retrospective records **prose advice** ("last time X went wrong when Y"). A
+> *structural fact* this run verified about a symbol or file — a consumer count
+> you swept, an invariant you confirmed, a defect you fixed at a SHA — is a
+> different thing: it belongs in the shared **`codebase-knowledge`** bucket under
+> a `knowledge::<symbol>@<path>` key, not here. See the intake step 6 write-back
+> note and the `lorekit-setup` skill, `§ Shared codebase-knowledge`.
+
 ## 2. Phrase it as an observation
 
 Write what happened and what worked, not a commandment.

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,47 @@ 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
+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

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.