@lorekit/cli 1.67.0 → 1.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.67.0",
+  "version": "1.68.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)
 

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

@@ -93,6 +93,23 @@ 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.
 
+## 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/self-improvement-loops.md

@@ -21,6 +21,8 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 - [Read step (start of every run)](#read-step-start-of-every-run)
 - [Write step (on failure / at the end of a run)](#write-step-on-failure--at-the-end-of-a-run)
 - [The reconcile-on-re-run flow (resolve + record)](#the-reconcile-on-re-run-flow-resolve--record)
+- [Cross-bucket reads (targeted, read-only)](#cross-bucket-reads-targeted-read-only)
+- [Shared codebase-knowledge (the standard cross-loop layer)](#shared-codebase-knowledge-the-standard-cross-loop-layer)
 - [Promotion (fast → slow)](#promotion-fast--slow)
 - [Entrenchment guards (do not skip these)](#entrenchment-guards-do-not-skip-these)
 - [Wiring checklist](#wiring-checklist)
@@ -247,6 +249,134 @@ record shape are specified in `agents/shared/rules/comment-relevance-memory.md`.
 
 ---
 
+## Cross-bucket reads (targeted, read-only)
+
+The default is strict: a loop reads **only its own bucket**, filtered by
+`loop::<host>-lessons`. That isolation is deliberate — it keeps one loop's
+lessons from drowning another's, and lets each read fire at its own cadence
+against its own decision point. Wholesale "read every lesson this repo knows"
+is an **anti-pattern**: it reintroduces exactly the noise the tag split exists
+to prevent, and buries the matches that would have fired.
+
+There is **one** shape of cross-bucket read that is safe and worth wiring: a host
+reading **another host's Signal or Knowledge bucket, matched by a structural key,
+strictly read-only**. Wire it only when all four hold:
+
+1. **The other bucket is keyed by something structural** — a `symbol@path`, a
+   file path, a stable fingerprint — never by prose. A structural key is what
+   makes a cross-host read meaningful: it matches the reader's own concrete work
+   (the files or symbols it is about to touch), not a vague topic.
+2. **The read is bounded to the reader's current work.** Match the other bucket's
+   keys against the paths / symbols this run will actually touch and ignore the
+   rest — never load the whole bucket as advice.
+3. **The reader treats it as advisory and re-verifies.** A cross-host fact can be
+   stale — it carries the *writer's* `verified_at_sha`, not the reader's. It
+   **raises care** (more coverage on a hotspot, design around a known invariant)
+   but never lowers a bar, skips a step, or suppresses a finding. An absent
+   record is never evidence of safety.
+4. **The reader never writes the other bucket.** Write ownership stays with the
+   one owning host; a second writer corrupts its provenance. Cross-host is a
+   **read** relationship only.
+
+Do **not** cross-read another host's `loop::<host>-lessons`. Lessons are prose
+"how to do better" advice tuned to that host's own decisions; they re-key on
+rephrasing and carry no structural anchor to match against, so a cross-read of
+them is the wholesale anti-pattern above. Only Signal / Knowledge buckets with
+structural keys qualify.
+
+LoreKit ships **one** standard instance of this pattern — the shared
+`codebase-knowledge` bucket that every code-touching loop reads and writes. It is
+the mechanism behind the automatic synergy below, and it is what makes a
+structural key worth insisting on: a fixed name plus a `symbol@path` key is what
+lets a loop wired by one person be consumed by a loop wired by another. It is
+specified in full next.
+
+---
+
+## Shared codebase-knowledge (the standard cross-loop layer)
+
+The cross-bucket read above becomes **automatic** through one bucket every LoreKit
+loop shares by name: `codebase-knowledge`. This is the reason two skills wired
+independently — by different people, in different sessions, in the same repo —
+still compound: they read and write the *same* repo-scoped, structurally-keyed
+record of what the codebase has taught every loop that touched it. A code-changing
+loop plans and edits with that history in hand instead of blind; and because the
+loops that consume it also feed it, the synergy appears for a user who wired a
+single skill and nothing else.
+
+### The bucket
+
+| Field | Value |
+| --- | --- |
+| **Tag** | `codebase-knowledge` |
+| **Kind** | `signal` (a durable per-repo filter, read on every run that touches code) |
+| **Scope** | `repo::{owner}/{repo}` — a codebase fact is repo-bound |
+| **TTL** | ~90 days, refreshed on re-verification |
+| **Keys** | `knowledge::<symbol>@<path>` — verified facts about one symbol (an invariant it holds, its consumer/dependent count, a defect it produced before); `hotspot::<path>` — per-file counters (`confirmed`, `regressed`, `missed`) |
+
+The keys are **structural** (`symbol@path`, `path`) on purpose: a key survives a
+rename of the *finding* but not a rename of the *code*, which is exactly the
+sensitivity that lets a different loop match it against the files it is about to
+touch. Set `kind: signal` and `host` explicitly on every write — LoreKit infers
+them only from a `loop::` tag, and this bucket is not tagged that way.
+
+### Read side — automatic for any code-touching host
+
+Wire it at the host's **plan/apply seam** — the moment it has the concrete
+file/symbol list it will change (a plan's File Changes list, an apply pack, a
+fix's target file):
+
+```text
+memory.list { scope: "repo::{owner}/{repo}", tags: ["codebase-knowledge"], limit: 100 }
+# keep only hotspot::<path> / knowledge::<symbol>@<path> whose <path> (and <symbol>)
+# this run will actually touch. Apply as PLANNING INPUTS: raise coverage on a
+# hotspot, design around a known invariant / consumer count. Advisory and
+# re-verified against the code — never a reason to skip a step or suppress a finding.
+```
+
+This is the read-side contract from [Cross-bucket reads](#cross-bucket-reads-targeted-read-only)
+made concrete: structural match, bounded to this run, advisory, an absent record
+never evidence of safety.
+
+### Write side — how the layer fills, and why many writers stay safe
+
+A host that **verifies** a structural fact contributes it back, so the next loop
+reads it. This is what makes the synergy automatic even for a user with one skill
+and no dedicated reviewer: the loops that consume the layer also feed it.
+Multi-writer is safe **only** behind this write contract — bake in every bullet,
+or do not wire the write:
+
+- **Structural key from a real symbol/path list**, never composed from prose. A
+  prose key accumulates nothing and no reader can match it.
+- **`verified_at_sha` on every fact** — the HEAD this run verified it at. It is the
+  whole mechanism the next reader uses to decide "fact stands" vs "re-verify"; an
+  absent or stale SHA makes the fact permanently unverifiable, and it is dropped.
+- **`source_agent` stamped** — which host verified it. Together with
+  `verified_at_sha` this is what makes many writers safe: a reader sees who
+  verified what, and when, so no writer silently overwrites another's provenance.
+- **Only what THIS run actually verified**, grounded in the code — never a guess,
+  and never a value about a person or a telemetry reading. A fact about code,
+  keyed to code.
+- **Merge, never clobber.** Read the existing record first; append to `history[]`
+  or increment counters (each capped) and carry the rest through unchanged. A
+  clobbered counter is indistinguishable from a first write.
+- **Raise care, never suppress.** These records only raise priority/coverage on a
+  file or symbol. They never lower a bar or silence a finding, and an absent record
+  is never evidence of safety. Suppression, if a host needs it, is a different
+  bucket behind verification (the Signal in the reconcile flow above).
+- **Explicit `kind: signal` + `host`, a TTL, and the privacy pre-flight** — as
+  every write in this skill.
+
+Because the name is fixed, the read is the same call in every host, and the write
+follows one contract, **any two LoreKit-wired loops in the same repo compound
+automatically** — which is the whole reason to standardize the name instead of
+letting each host invent its own. The reference ecosystem is `agent-skills`: the
+`pr-reviewer` agent is the primary writer (it verifies symbol facts and file
+hotspots during review), and every code-changing host — `aw`, `implement-suggestion`,
+`fix-bug`, `ci-auto-fix` — reads the layer at its plan/apply seam.
+
+---
+
 ## Promotion (fast → slow)
 
 After a read or write, a lesson is **promotion-eligible** when either:
@@ -316,6 +446,10 @@ To add a loop to a host called `<host>`:
 - [ ] State the **entrenchment guards** so a future maintainer does not "optimize
       them away".
 - [ ] Confirm the loop **degrades silently** when `memory.*` is not connected.
+- [ ] If the host **touches code**, wire the **[codebase-knowledge](#shared-codebase-knowledge-the-standard-cross-loop-layer)
+      read** at its plan/apply seam (match `hotspot::<path>` /
+      `knowledge::<symbol>@<path>` to the files it will change). If it **verifies**
+      a structural fact, wire the **write** behind that section's contract.
 
 ---