@lorekit/cli 1.69.0 → 1.70.0

package/skill/lorekit-setup/rules/proving-improvement.md

@@ -0,0 +1,111 @@
+# Proving a loop improved something
+
+A loop that nobody can see helping is indistinguishable from no loop. Wiring is not
+the deliverable — **a real failure that stops recurring** is. This file is how you show
+that, and — as important — how you avoid fooling yourself with numbers that cannot prove
+it.
+
+## Contents
+
+- [The required proof: the immunity re-challenge](#the-required-proof-the-immunity-re-challenge)
+- [Why the raw counters cannot prove causation](#why-the-raw-counters-cannot-prove-causation)
+- [The optional counter view (advisory only)](#the-optional-counter-view-advisory-only)
+- [Declare the metric at wiring time](#declare-the-metric-at-wiring-time)
+- [The north star: a withheld-memory control arm](#the-north-star-a-withheld-memory-control-arm)
+- [Guards](#guards)
+
+---
+
+## The required proof: the immunity re-challenge
+
+There is exactly one proof this skill *requires*, because it is the one a doc can make
+a person actually run and the one that survives the confounds below: **after you promote
+a lesson to a rule, its failure signature should stop recurring.**
+
+Borrowed from immune memory: promoting a lesson registers its original failure
+signature as a "pathogen"; a later write bearing that same signature is a re-infection.
+
+1. **At promotion, record the signature.** The lesson's **Applies when** line *is* the
+   signature — a file glob, a task type, a tool name, an error shape. Note the source
+   lesson's key and its `seen_count` at the moment of promotion.
+2. **Watch for recurrence.** The direct measurement is the source lesson's `seen_count`
+   going **flat** — the loop stops writing that lesson because the failure stopped
+   happening. Read the column (`memory.read` / `lorekit show`), never a number in the
+   body.
+3. **Escalate a breakthrough.** Any new write matching the promoted signature is a
+   vaccine-breakthrough case: the rule did not hold. That is a signal to fix the rule
+   (too narrow, wrong shape), not to shrug.
+
+A promoted rule's value is the **silence** of its failure signature afterward. You
+measure the absence. This needs no new product feature — `seen_count` and the
+**Applies when** line already exist.
+
+## Why the raw counters cannot prove causation
+
+It is tempting to prove a loop "works" by pointing at rising counters. Do not lead with
+this — LoreKit's own analysis records why the absolute counters are confounded:
+
+- **`read_count` is ~99.8% bulk ride-alongs** — it tracks scope breadth, not whether a
+  lesson mattered.
+- **`seen_count` is `1` for ~88% of rows** — most lessons never recur, so a raw count is
+  mostly noise.
+- **Pull-through (`opened_count / read_count`) is the only trustworthy value signal** —
+  it cancels the ride-along confound by dividing it out.
+
+And even pull-through is *correlation*: a lesson can pull through because it was
+genuinely useful, or because the task was easy and any nudge looked right. Counter
+movement alone can never separate "the lesson helped" from "the run would have
+succeeded anyway." Only a run that deliberately did **not** get the memory can — see
+[the north star](#the-north-star-a-withheld-memory-control-arm).
+
+## The optional counter view (advisory only)
+
+Once the immunity check is in place, the counters are a useful *secondary* read — never
+the headline:
+
+- **Pull-through per bucket** — `opened_count / read_count` across `loop::<host>-lessons`.
+  A bucket read often and opened rarely is dead weight to prune, not proof of value.
+- **`/insights`** — the dashboard's Lore Utility grid classifies each lesson
+  (load-bearing / specialist / noise-tax / dormant) from pull-through against an
+  evidence floor. Consult it to find lessons to promote (load-bearing) or retire
+  (noise-tax), not to claim the loop improved a host.
+- **`cited_count`** — when a host cites the lessons it applied (`cited` on the write),
+  a rising `cited_count` on a lesson is *evidence* it is being used. It is evidence,
+  never a denominator: a `0` means "nobody said so", not "unused".
+
+State the confound wherever you report these: raw counters describe supply, not lift.
+
+## Declare the metric at wiring time
+
+Do this at step 6 of the quickstart, not months later when you have forgotten what
+"better" meant:
+
+- **Required:** name the failure signature (the **Applies when** line) whose recurrence
+  you will watch after promotion.
+- **Optional:** name the one bucket pull-through you will glance at, and the interval.
+- Write it into the host's own docs next to the loop's read/write steps, so a future
+  maintainer inherits the definition of "working" instead of re-inventing it.
+
+## The north star: a withheld-memory control arm
+
+The only *rigorous* attribution is a control arm: deterministically bucket a small
+fraction of runs into a **lessons-suppressed** arm (reuse LoreKit's feature-flags
+FNV-1a bucketing on a stable run id), then compare outcome rates — retry count,
+first-try pass, wall-clock — between treated and control. That yields lift with a
+confidence interval instead of a ratio.
+
+This is the aspiration, **not a requirement**, for two honest reasons: it needs product
+infrastructure that does not exist yet (a per-loop lift harness), and deliberately
+withholding memory has a real UX/ethics cost, so it must be opt-in. Treat it as the
+direction of travel; ship the immunity re-challenge today.
+
+## Guards
+
+- **Do not measure a loop you seeded.** Cold-start seeding erases the clean baseline the
+  immunity check reads — see [cold-start-seeding.md](./cold-start-seeding.md). Pick, per
+  loop: run-one value (seed it) OR provable lift (leave it cold).
+- **A flat `seen_count` after promotion is proof only if the loop is still firing.**
+  Confirm the loop is alive first ([loop-health.md](./loop-health.md#is-the-loop-firing));
+  a dead loop also has a flat count, for the wrong reason.
+- **Never gate anything on a counter.** These are proof for a human, not a machine gate.
+  The only mechanical gate is the compiled invariant ([compiled-invariants.md](./compiled-invariants.md)).

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

@@ -15,6 +15,7 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 
 ## Contents
 
+- [Find where a loop pays off](#find-where-a-loop-pays-off)
 - [When to add a loop (and when not to)](#when-to-add-a-loop-and-when-not-to)
 - [The two tiers](#the-two-tiers)
 - [Conventions](#conventions)
@@ -30,6 +31,41 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 
 ---
 
+## Find where a loop pays off
+
+Do not ask a newcomer to *guess* where memory helps — the best place for a loop is a
+statistical property of the codebase's own history, and the data already knows it. Answer
+"where?" before "how?".
+
+**Start from recurring pain, not from a host you happen to be looking at.** A loop earns
+its keep only where the same class of failure happens more than once. Two ways to surface
+that:
+
+- **From the store, if loops already exist:** `lorekit dedupe` clusters near-duplicate
+  lessons, and `lorekit invariants candidates` ranks clusters by summed `seen_count` ×
+  distinct scopes — literally "how often, in how many places, did this recur." A high-
+  ranked cluster with no dedicated host is a loop waiting to be wired.
+- **From history, on a cold repo:** the same pattern fixed the same way 3+ times, a
+  revert-then-refix chain, a review note left across many PRs, or an existing CI guard —
+  each is a lesson someone already learned. `git log`, `git log --grep=revert`, and the
+  `obligations-map` are the seams. These double as seed sources —
+  [cold-start-seeding.md](./cold-start-seeding.md).
+
+**Then match the host to an archetype** and copy its recipe card rather than wiring from
+scratch:
+
+| The host… | Card |
+| --------- | ---- |
+| edits code, fails in recurring ways | [code-changing-agent](../templates/code-changing-agent.md) |
+| posts durable outputs at a target it revisits | [reviewer-reconcile-host](../templates/reviewer-reconcile-host.md) |
+| is a pipeline that fails in classifiable ways | [multi-step-orchestrator](../templates/multi-step-orchestrator.md) |
+| is a deterministic CI job needing last-run state | [ci-job](../templates/ci-job.md) |
+
+The abstract test in the next section is the fallback when no recurrence data exists yet —
+apply it, but prefer the evidence above when you have it.
+
+---
+
 ## When to add a loop (and when not to)
 
 Add a loop when **all** of these hold:
@@ -220,13 +256,17 @@ readable start to finish.
 
 ## Read step (start of every run)
 
-Read narrow-to-broad, filtered by the bucket tag, and merge:
+Read narrow-to-broad, filtered by the bucket tag, and merge — but **capped**. A loop
+injects at most a small N (`limit: 5` per scope by default) into a run. This is a wiring
+precondition, not a tuning knob: many uncapped loops on the same scopes tax every
+session's context until agents learn to ignore injected lore entirely. Raise N only with
+a reason.
 
 ```text
-memory.list { scope: "repo::{owner}/{repo}", tags: ["loop::<host>-lessons"], limit: 50 }   # skips silently if memory.* not connected
-memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 50 }
+memory.list { scope: "repo::{owner}/{repo}", tags: ["loop::<host>-lessons"], limit: 5 }   # skips silently if memory.* not connected
+memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 5 }
 # when the run names a subsystem / error, add a search:
-memory.search { q: "<keywords>", scopes: ["repo::{owner}/*", "global"], limit: 10 }
+memory.search { q: "<keywords>", scopes: ["repo::{owner}/*", "global"], limit: 5 }
 ```
 
 Then:
@@ -557,6 +597,14 @@ To add a loop to a host called `<host>`:
       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.
+- [ ] Set the **injection cap** (`limit: 5` per scope by default) on the read step —
+      a wiring precondition, not a tuning knob.
+- [ ] Decide **seeding**: value on run one ([cold-start-seeding.md](./cold-start-seeding.md),
+      a handful, curated) **or** provable lift (leave it cold) — never both.
+- [ ] Declare the **proof** — the immunity re-challenge whose failure signature you will
+      watch after promotion ([proving-improvement.md](./proving-improvement.md)).
+- [ ] Add the **health checks** — a canary, the write-time matchability check, and the
+      quarantine-not-delete rollback ([loop-health.md](./loop-health.md)).
 
 ---
 

package/skill/lorekit-setup/rules/team-and-portfolio.md

@@ -0,0 +1,107 @@
+# Team & portfolio — from one loop to a practice
+
+Everything else in this skill is written for one person wiring one host. But the store
+is shared, and that changes the economics: a lesson one person's loop writes can rescue
+another person's host, the same pain relearned by three people is a louder signal than
+any single run, and a new hire can inherit years of accumulated workflow intelligence on
+day one. This file is how a team turns scattered loops into a compounding practice.
+
+Some of this is guidance a person acts on today; some names a dashboard/product surface
+that would make it turnkey (flagged **[product]**).
+
+## Contents
+
+- [The rediscovery signal: where a team loop pays off](#the-rediscovery-signal-where-a-team-loop-pays-off)
+- [The maturity model](#the-maturity-model)
+- [Promotion as review](#promotion-as-review)
+- [Onboarding: inherit the lore](#onboarding-inherit-the-lore)
+- [Cross-host portability](#cross-host-portability)
+- [Governance is mostly self-executing](#governance-is-mostly-self-executing)
+
+---
+
+## The rediscovery signal: where a team loop pays off
+
+At single-host scale, `seen_count` is a promotion trigger. At team scale it is a
+**rediscovery counter**: the same lesson climbing in count across **distinct authors and
+scopes** is proof a pain is *shared*, not personal — and shared pain is exactly where a
+team-wide loop or rule pays off most.
+
+Find it with the tools that already exist:
+
+- `lorekit dedupe` — near-duplicate lessons written independently by different people are
+  one shared lesson wearing several names; the cluster's summed `seen_count` is the team
+  signal.
+- `lorekit invariants candidates` — ranks clusters by summed `seen_count` × distinct
+  scopes, which is precisely "how many people, in how many places, hit this."
+- **[product]** A dashboard "rediscovery radar" that surfaces cross-author clusters with
+  a one-click "wire a loop here" would make this turnkey.
+
+## The maturity model
+
+The FAST → SLOW → compiled-invariant rungs describe one loop's lifecycle. Aggregated
+across every host, they become a **portfolio view** that shows where the team's loops are
+thin:
+
+| Level | State | Evidence |
+| ----- | ----- | -------- |
+| **L0** | No loop | The host has no `loop::<host>-lessons` bucket |
+| **L1** | Fast advisories only | Lessons accrue and are read; nothing promoted yet |
+| **L2** | Slow promotions landing | Recurring lessons hardened into host rules (`status::promoted`) |
+| **L3** | Compiled invariant | A mechanically-checked `obligations-map` entry, `gating` |
+
+Plot each workflow's level against how many teammates actually run it. A high-traffic
+workflow stuck at L0/L1 is the team's biggest missed compounding. **[product]** A
+maturity board on `/insights` would render this from the tags and counters that already
+exist.
+
+## Promotion as review
+
+Promoting a `repo::` lesson to a team rule is a governance moment, and it maps cleanly
+onto a process the team already trusts — code review:
+
+1. A promotion-eligible lesson (`seen_count >= 3` or `status::structural`) enters a
+   "pending team rule" state.
+2. A **second engineer** reviews it, exactly as they would a PR. The gate the loop
+   computes automatically becomes the human checkpoint.
+3. On approval, the promotion is a normal reviewed edit to the repo's rules/docs; add a
+   `status::promoted` tag so it stops re-suggesting and stands as an audit trail.
+4. On rejection, write a lesson about **why it was not generalized** — that reasoning is
+   itself reusable.
+
+## Onboarding: inherit the lore
+
+Onboarding content does not need to be written — it is the exact bucket an agent already
+reads at SessionStart, re-aimed at a human. Generate a new hire's "what this team learned
+the hard way" brief from:
+
+- the highest-`seen_count` and `status::promoted` lessons per repo (rules first),
+- the `codebase-knowledge` hotspots and invariants (where the bodies are buried),
+- ordered by rung: promoted rules, then advisories.
+
+Because it is derived from the live store, it is never stale and needs no maintenance.
+
+## Cross-host portability
+
+Eight people on Claude Code, Cursor, and Codex normally fragment knowledge into per-tool
+silos. The shared store lets host-diversity be an *asset* instead:
+
+- **Host-tag every lesson** (the `host` field). A lesson read by a *different* host than
+  wrote it is portable; one only ever read within its authoring host may be host-local.
+- **A lesson proven across two hosts is stronger evidence** it is a real team rule than
+  one seen within a single tool — weight it higher at promotion.
+- At promotion to a team rule, **strip host-specific phrasing** ("in Claude Code, …") so
+  the rule reads for any host.
+
+## Governance is mostly self-executing
+
+The failure mode of "team governance" is that it assumes a human process watching loops
+decay — which solo devs and small teams skip, so entrenchment guards rot. Lean on the
+mechanisms that need no staffing:
+
+- **TTL expiry** drops stale lessons automatically — decay is built in, not a chore.
+- **The recurrence gate** means a single bad run can never rewrite a host.
+- **The injection cap** bounds read cost no matter how the bucket grows.
+
+The only step that genuinely needs a human is **promotion review** above. Keep the
+staffed surface that small; let the defaults do the rest.

package/skill/lorekit-setup/templates/README.md

@@ -0,0 +1,26 @@
+# Loop recipe cards
+
+Copy-paste starters for wiring a self-improvement loop into a host. Pick the card
+that matches your host, paste its read/write steps at the seams it names, and fill in
+`<host>` / `<owner>/<repo>`. Each card already bakes in the five non-negotiables from
+the skill's [Non-negotiables](../SKILL.md#non-negotiables-do-not-optimize-these-away):
+a per-host **injection cap**, a **TTL**, the **advisory-only** contract, the **body
+contract** (pure markdown), and a **fire-once check** so you prove the loop closes
+before you trust it.
+
+| Card | Use it for | Shape |
+| ---- | ---------- | ----- |
+| [code-changing-agent.md](./code-changing-agent.md) | A host that edits code and can fail in recurring ways (an autonomous workflow, a fix/implement agent) | Lessons loop + the shared `codebase-knowledge` read/write |
+| [reviewer-reconcile-host.md](./reviewer-reconcile-host.md) | A host that posts durable outputs at a shared target it revisits (a PR reviewer, a triager, a linter that files tickets) | Lessons loop + the reconcile-on-re-run Signal bucket |
+| [multi-step-orchestrator.md](./multi-step-orchestrator.md) | A pipeline that fails in classifiable ways (wrong triage, a missed step, a false-green gate) | The plain two-tier lessons loop |
+| [ci-job.md](./ci-job.md) | A deterministic job that needs last-run state (flaky set, last deployed SHA, a baseline) | JSON state records, not lessons |
+
+Every card is a *starting point*, not a spec. The authoritative rules are one level up:
+[self-improvement-loops.md](../rules/self-improvement-loops.md) (lessons),
+[ci-state-records.md](../rules/ci-state-records.md) (state records),
+[proving-improvement.md](../rules/proving-improvement.md) (proof),
+[loop-health.md](../rules/loop-health.md) (maintenance).
+
+**`N` — the injection cap — is `5` in every card by default.** Raise it only with a
+reason; a loop that reads 30 lessons into every run is why agents learn to ignore
+injected lore. See [Non-negotiables #2](../SKILL.md#non-negotiables-do-not-optimize-these-away).

package/skill/lorekit-setup/templates/ci-job.md

@@ -0,0 +1,90 @@
+# Recipe card — CI job (state record, not a lesson)
+
+For a **deterministic job** — a GitHub Actions workflow, a cron script, a release
+pipeline — that needs to know *what happened last time*: which tests flaked, the last
+benchmark number, the last deployed SHA. This is **not** a lessons loop: nothing here
+is authored or interpreted by a model, so there is no `seen_count`, no promotion, no
+entrenchment guard. A different, smaller set of guards applies. Full rule:
+[ci-state-records.md](../rules/ci-state-records.md).
+
+Fill in: `<job>` (e.g. `test`), `<slug>` (e.g. `flaky-tests`), `<owner>/<repo>`.
+
+> Use `actions/cache` instead if **only** the next CI run will ever read this. LoreKit
+> earns its place only when the fact is *also* useful to an agent or a human.
+
+## Bucket
+
+- Tag `ci::<job>-state` (deliberately NOT `loop::…`). Key `ci-state::<slug>`, one slug
+  per fact, **overwritten in place** — never one key per run.
+- Taxonomy: pass `--kind bus --host ci` explicitly, or the record leaks into every
+  session's SessionStart digest as a raw JSON blob.
+
+## Record shape (versioned JSON)
+
+```json
+{
+  "v": 1,
+  "updated_by_run": "https://github.com/<owner>/<repo>/actions/runs/123",
+  "commit": "0f4a1c9…",
+  "data": { "flaky": ["src/queue.test.ts::retries on 429"], "consecutive_green": 3 }
+}
+```
+
+## Read step — early in the job
+
+```bash
+set -euo pipefail
+STATE_JSON='{}'
+if lorekit show --scope "repo::<owner>/<repo>" --key 'ci-state::<slug>' --remote --json > state.json 2>&1; then
+  cat state.json                                   # always echo — never `|| true`
+  STATE_JSON=$(jq -r '.remote.record.value // "{}"' state.json)
+else
+  cat state.json
+  echo "No prior state (first run, or LoreKit unreachable) — continuing with defaults."
+fi
+VERSION=$(jq -r '.v // 0' <<<"$STATE_JSON")
+[ "$VERSION" = "1" ] || { echo "State schema v${VERSION} != v1 — rebuilding."; STATE_JSON='{}'; }
+```
+
+`lorekit show` exits 1 on a miss — that is the first run, branch on it; do not `|| true`
+it away (that swallows a real auth/network failure too).
+
+## Write step — end of job (`if: always()` if state should survive a failing run)
+
+```bash
+set -euo pipefail
+jq -nc \
+  --arg run "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" \
+  --arg sha "${GITHUB_SHA}" \
+  --argjson data "$NEW_DATA" \
+  '{v: 1, updated_by_run: $run, commit: $sha, data: $data}' \
+| lorekit write \
+    --scope "repo::<owner>/<repo>" --key 'ci-state::<slug>' \
+    --tags 'ci::<job>-state' --kind bus --host ci \
+    --ttl-days 7 --remote --json \
+| tee write.log \
+|| echo "LoreKit write failed (exit $?) — not failing the build; see output above."
+```
+
+`--ttl-days` is **not optional** and should be short (7 for daily jobs) — it refreshes
+every write, so it expires only when the *job* goes silent. See
+[TTL is a liveness guard](../rules/ci-state-records.md#ttl-is-a-liveness-guard).
+
+## Tokens
+
+Write with a **write-only `lk_wo_*`** token (a leaked CI token then cannot exfiltrate
+the team's lore); read with `lk_ro_*`; use `lk_rw_*` only where one job genuinely needs
+both.
+
+## Guards (do not skip)
+
+Bounded cardinality (one key per fact) · no secrets, ever (build the payload from an
+allow-list, never `env | jq -R`) · explicit short TTL · never on the critical path
+(a store outage logs and continues) · last-write-wins (serialise with a `concurrency`
+group) · version every record. Full list:
+[Guards](../rules/ci-state-records.md#guards-do-not-skip-these).
+
+## Verify
+
+Run the job twice; confirm `lorekit list --kind bus --host ci` still shows **one** row
+per fact (key count must not grow with run count).

package/skill/lorekit-setup/templates/code-changing-agent.md

@@ -0,0 +1,89 @@
+# Recipe card — code-changing agent
+
+For a host that **edits code** and fails in recurring ways: an autonomous workflow, a
+fix-bug agent, an implement-suggestion worker. It wants two reads — its own lessons
+*and* the shared `codebase-knowledge` for the files it is about to touch — and two
+writes — a lesson on failure, and a verified structural fact back to
+`codebase-knowledge`.
+
+Fill in: `<host>` (e.g. `fix-bug`), `<owner>/<repo>`. `N = 5`.
+
+## Bucket
+
+- Lessons: tag `loop::<host>-lessons`, key `<host>-lessons::<slug>`.
+- Shared: tag `codebase-knowledge` (read by every code-touching loop; see
+  [the shared layer](../rules/self-improvement-loops.md#shared-codebase-knowledge-the-standard-cross-loop-layer)).
+
+## Read step — at the start of the run AND at the plan/apply seam
+
+```text
+# 1. Own lessons, narrow-to-broad, capped at N per scope:
+memory.list { scope: "repo::<owner>/<repo>", tags: ["loop::<host>-lessons"], limit: 5 }
+memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 5 }
+
+# 2. When the run names a subsystem/error, one targeted search:
+memory.search { q: "<keywords>", scopes: ["repo::<owner>/*", "global"], limit: 5 }
+
+# 3. At the plan/apply seam — once you have the concrete file/symbol list:
+memory.list { scope: "repo::<owner>/<repo>", tags: ["codebase-knowledge"], limit: 100 }
+#   keep ONLY hotspot::<path> / knowledge::<symbol>@<path> whose <path>/<symbol>
+#   this run will touch. Apply as PLANNING INPUT: raise coverage on a hotspot,
+#   design around a known invariant. Advisory; re-verify against the code.
+```
+
+Match each lesson's **Applies when** line against the current run; apply matching
+**Do this instead** lines as *considerations*, not commands. On a `repo::` vs `global`
+collision, `repo::` wins. An absent `codebase-knowledge` record is never evidence of
+safety.
+
+## Write step — on failure / at end of run
+
+```text
+# Dedup first so a recurrence UPDATEs in place:
+memory.search { q: "<key words of the lesson>", scopes: ["repo::<owner>/<repo>", "global"], limit: 10 }
+
+memory.write {
+  scope:    "<global | repo::<owner>/<repo>>",   # repo:: if it names a repo path/term, else global
+  key:      "<host>-lessons::<slug>",
+  value:    "<markdown lesson body — no hidden blocks>",
+  tags:     ["loop::<host>-lessons", "source::<trigger>"],
+  trigger:  "<stuck-loop | command-failure | gotcha | near-miss | assumption-wrong | paid-off>",
+  ttl_days: 90
+}
+```
+
+If the host **verified** a structural fact this run (an invariant a symbol holds, a
+file that produced a defect), write it back to `codebase-knowledge` under the
+multi-writer contract — `verified_at_sha`, `source_agent`, merge-not-clobber, raise
+care never suppress:
+[write side](../rules/self-improvement-loops.md#write-side--how-the-layer-fills-and-why-many-writers-stay-safe).
+
+## Lesson body — copy this shape
+
+```markdown
+# <one-line takeaway — what to do, not what it is about>
+
+**Applies when:** <concrete signal — file glob, task type, tool name, error shape>
+
+**What happened:** <the concrete observable>
+**Why:** <root cause, or "unknown">
+**Do this instead:** <prescriptive, testable instruction>
+**Promotion target:** <the host rule this would harden if promoted, or "none">
+```
+
+## Fire-once check (do this before trusting the loop)
+
+1. Trigger the failure this loop is meant to catch.
+2. Confirm the lesson landed: `memory.list { scope: "<expected>", tags: ["loop::<host>-lessons"], limit: 10 }`.
+3. Re-run over the same situation; confirm it surfaces in the read step and biases the run.
+
+## Cold start (optional, capped)
+
+Pre-seed a *handful* of real lessons from git history / prior review threads so run one
+is not empty — [cold-start-seeding.md](../rules/cold-start-seeding.md). Do **not** seed
+a loop whose lift you intend to measure; it erases the baseline.
+
+## Prove it
+
+Declare the immunity re-challenge at wiring time: after you promote a lesson to a rule,
+its failure signature should stop recurring — [proving-improvement.md](../rules/proving-improvement.md).

package/skill/lorekit-setup/templates/multi-step-orchestrator.md

@@ -0,0 +1,76 @@
+# Recipe card — multi-step orchestrator
+
+For a **pipeline that fails in classifiable ways** but does not post durable outputs at
+a shared target and does not (necessarily) edit code: a triage → plan → execute
+workflow, a release orchestrator, a batch processor. The plain two-tier lessons loop
+fits it exactly. This is the card to start from when no other card matches.
+
+Fill in: `<host>` (e.g. `deploy`), `<owner>/<repo>`. `N = 5`.
+
+## Bucket
+
+Tag `loop::<host>-lessons`, key `<host>-lessons::<slug>`. One bucket per host.
+
+## Read step — start of every run
+
+```text
+memory.list { scope: "repo::<owner>/<repo>", tags: ["loop::<host>-lessons"], limit: 5 }
+memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 5 }
+# when the run names a stage/error, one targeted search:
+memory.search { q: "<keywords>", scopes: ["repo::<owner>/*", "global"], limit: 5 }
+```
+
+Match each **Applies when** against the current run; apply matching **Do this instead**
+lines as considerations. `repo::` beats `global` on a collision.
+
+## Write step — at the host's EXISTING failure points
+
+Do not add a new reflection stage — hook the points the host already detects (a stuck
+loop, a repeated failure, a gate that should have caught something, a near-miss, a
+guess that paid off). Not on smooth successes.
+
+```text
+memory.search { q: "<key words of the lesson>", scopes: ["repo::<owner>/<repo>", "global"], limit: 10 }
+
+memory.write {
+  scope:    "<global | repo::<owner>/<repo>>",
+  key:      "<host>-lessons::<slug>",
+  value:    "<markdown lesson body — no hidden blocks>",
+  tags:     ["loop::<host>-lessons", "source::<trigger>"],   # + "status::structural" when it is
+  trigger:  "<stuck-loop | command-failure | gotcha | near-miss | assumption-wrong | paid-off>",
+  ttl_days: 90
+}
+```
+
+Same `scope` + `key` UPDATEs in place — the store increments `seen_count` for you and
+re-passing `ttl_days` refreshes the expiry. Never hand-write a count into the body.
+
+## Lesson body — copy this shape
+
+```markdown
+# <one-line takeaway — what to do, not what it is about>
+
+**Applies when:** <concrete signal — stage name, task type, tool name, error shape>
+
+**What happened:** <the concrete observable>
+**Why:** <root cause, or "unknown">
+**Do this instead:** <prescriptive, testable instruction>
+**Promotion target:** <the host step this would harden if promoted, or "none">
+```
+
+## Promotion
+
+When a lesson hits `seen_count >= 3` (read the column, not the body) or carries
+`status::structural`, surface a one-line promotion suggestion — never act silently.
+See [Promotion](../rules/self-improvement-loops.md#promotion-fast--slow).
+
+## Fire-once check
+
+1. Force the failure this loop targets.
+2. `memory.list { scope: "<expected>", tags: ["loop::<host>-lessons"], limit: 10 }` — confirm the lesson.
+3. Re-run; confirm it surfaces and biases the run.
+
+## Cold start & proof
+
+Optional capped seeding: [cold-start-seeding.md](../rules/cold-start-seeding.md).
+Required proof — the immunity re-challenge: [proving-improvement.md](../rules/proving-improvement.md).