@lorekit/cli 1.68.0 → 1.70.0

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).

package/skill/lorekit-setup/templates/reviewer-reconcile-host.md

@@ -0,0 +1,86 @@
+# Recipe card — reviewer / reconcile host
+
+For a host that **produces durable outputs at a shared target it revisits**: a PR
+reviewer posting comment threads it re-reviews on every push, a triager filing issues
+it re-scans, a linter opening tickets. A plain read/write loop is not enough — stale
+outputs pile up at the target and the signal about which outputs were *useful* is
+thrown away. This card adds the **reconcile-on-re-run** flow on top of the lessons
+loop, feeding a second **Signal** bucket.
+
+Fill in: `<host>` (e.g. `reviewer`), `<signal>` (e.g. `comment-relevance`),
+`<owner>/<repo>`. `N = 5`.
+
+## Buckets (two)
+
+- Lessons: tag `loop::<host>-lessons`, key `<host>-lessons::<slug>` — how to review better.
+- Signal: tag `loop::<host>-<signal>`, key `<host>-<signal>::<pattern-fingerprint>` —
+  which of the host's OUTPUT PATTERNS get acted on vs declined at this target.
+
+## Read step — start of run
+
+```text
+# Own lessons (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 }
+
+# Signal bucket — suppress reliably-declined patterns, reinforce reliably-resolved ones:
+memory.list { scope: "repo::<owner>/<repo>", tags: ["loop::<host>-<signal>"], limit: 20 }
+```
+
+## Reconcile step — at the re-run seam, gated on "a prior output exists at this target"
+
+For each prior output the host itself authored, classify against the current target:
+
+| Outcome | Meaning | Evidence |
+| --- | --- | --- |
+| **resolved** | acted on — the flagged thing is handled | the region changed and the finding no longer reproduces, or the owner acknowledged it |
+| **declined** | explicitly rejected | a "won't fix" / "by design" reply, a 👎 |
+| **still-open** | still reproduces this run | the host re-produces the same output |
+
+Then:
+
+1. **Clean up** `resolved` + `declined` at the source (resolve the thread, close the
+   ticket). **Never** touch a `still-open` output. Only ever touch outputs the host
+   authored. Cleanup is idempotent and non-fatal (a cleanup error is logged, never
+   fails the run).
+2. **Record the outcome** to the Signal bucket, keyed by a stable pattern fingerprint
+   (never a line number or a drifting id):
+
+```text
+memory.write {
+  scope:    "repo::<owner>/<repo>",
+  key:      "<host>-<signal>::<pattern-fingerprint>",
+  value:    "<markdown: the pattern, and resolved-vs-declined evidence — no hidden blocks>",
+  tags:     ["loop::<host>-<signal>", "status::<resolved | declined>"],
+  trigger:  "reconcile",
+  ttl_days: 90
+}
+```
+
+`still-open` writes nothing — there is no outcome yet. **Absence of confirmation is not
+resolution**: if a re-run did not re-scan the region a prior output covers, it is
+`still-open`, not `resolved`.
+
+## Write step (lessons) — on friction, as usual
+
+Same as any lessons loop — see [code-changing-agent.md](./code-changing-agent.md#write-step--on-failure--at-end-of-run)
+for the write shape.
+
+## Fire-once check
+
+1. Produce an output at a test target, then resolve it at the source by hand.
+2. Re-run; confirm the host classifies it `resolved`, cleans it up, and writes a
+   positive Signal record for its pattern.
+3. Start a third run; confirm the Signal record surfaces and reinforces that pattern.
+
+## Reference implementation
+
+The `agent-skills` `pr-reviewer` agent: it resolves its own addressed PR threads on
+each commit-triggered re-review and records the fixed/declined outcome to a
+`reviewer-comment-relevance` bucket. Full flow:
+[the reconcile-on-re-run flow](../rules/self-improvement-loops.md#the-reconcile-on-re-run-flow-resolve--record).
+
+## Prove it
+
+[proving-improvement.md](../rules/proving-improvement.md) — for this host the signal is
+the **decline rate** of the host's outputs trending down over runs.

package/src/commands/invariants.mjs

@@ -14,15 +14,16 @@
 //
 // Criteria (pure scoring in `../shared/candidates-pure.mjs`):
 //   - summed seen_count across a cluster's members >= --min-seen-count
-//     (default 3), OR any member's `<!-- meta: ... status=... -->` comment
-//     already declares a non-"active" status
+//     (default 3), OR any member already declares a non-"active" status —
+//     a `status::<value>` tag, or a legacy `<!-- meta: ... status=... -->`
+//     comment for lessons written before tags were the convention
 //   - ranked by (summed seen_count × distinct scopes), descending
 //
 // What this deliberately does NOT do:
-//   - classify a trigger-context into a glob/command/error-shape. The raw
-//     `trigger-context` string (when a lesson's meta comment carries one) is
-//     printed verbatim, never interpreted — "parses into a detectable
-//     trigger" is the human step the compile pipeline protects.
+//   - classify an applicability signal into a glob/command/error-shape. The raw
+//     string (a lesson's `**Applies when:**` line, or a legacy meta comment's
+//     `trigger-context`) is printed verbatim, never interpreted — "parses into
+//     a detectable trigger" is the human step the compile pipeline protects.
 //   - check `compiled_to`. No such field exists yet (no schema, no server
 //     support — see the kickoff's Open Questions), so a candidate already
 //     compiled into an obligations-map.mjs entry can still surface here. A
@@ -150,7 +151,13 @@ function buildCandidates(entries, { threshold, minSeenCount }) {
     ...cl,
     members: cl.members.map((m) => {
       const raw = byAddress.get(`${m.scope}::${m.key}`);
-      return { scope: m.scope, key: m.key, seenCount: seenCountOf(raw), value: raw?.value ?? '' };
+      return {
+        scope: m.scope,
+        key: m.key,
+        seenCount: seenCountOf(raw),
+        value: raw?.value ?? '',
+        tags: Array.isArray(raw?.tags) ? raw.tags : [],
+      };
     }),
   }));
   return rankCandidates(clusters, { minSeenCount, resolveClass: resolveRecurrenceClass });
@@ -221,7 +228,7 @@ async function candidates(args) {
     heading('LoreKit invariants candidates');
     log(`  project: ${c.dim(root)}`);
     log(`  scopes:  ${scopes.join('  →  ')}`);
-    log(`  ${c.dim(`criteria: summed seen_count >= ${minSeenCount}, or a member's meta status is non-"active"`)}`);
+    log(`  ${c.dim(`criteria: summed seen_count >= ${minSeenCount}, or a member's status is non-"active"`)}`);
 
     if (offlineSection.available && offlineSection.popCapped) {
       log(`  ${c.yellow('!')} population cap (${POP_CAP}) reached for Offline — results are partial. Narrow with --key-prefix, --since, or --max.`);
@@ -281,8 +288,8 @@ function renderSection(header, section) {
     }
     for (const m of cand.members) {
       const fields = [`seen_count=${m.seenCount}`];
-      if (m.meta.status) fields.push(`status=${m.meta.status}`);
-      if (m.meta['trigger-context']) fields.push(`trigger-context=${JSON.stringify(m.meta['trigger-context'])}`);
+      if (m.status) fields.push(`status=${m.status}`);
+      if (m.appliesWhen) fields.push(`applies-when=${JSON.stringify(m.appliesWhen)}`);
       log(`    ${c.cyan('-')} ${m.scope}::${m.key}  ${c.dim(`(${fields.join(', ')})`)}`);
     }
   }

package/src/commands/lint.mjs

@@ -1,8 +1,10 @@
 // `lorekit lint` — flag low-quality lessons across the applicable scopes and
 // both stores. Each finding names the rule it violated (empty/whitespace value,
 // suspiciously short value, untrimmed value, empty key, volatile key, malformed
-// scope). The rules are pure predicates in `lessons-view.mjs` (`LINT_RULES` /
-// `lintEntry`), each independently unit-tested.
+// scope, unkinded state record, hidden metadata — an HTML comment / front-matter /
+// `key=value` header in a body that should be pure markdown). The rules are pure
+// predicates in `lessons-view.mjs` (`LINT_RULES` / `lintEntry`), each
+// independently unit-tested.
 //
 // Exit convention: `lint` exits NON-ZERO (1) when any finding exists, so it is
 // usable as a CI gate (`lorekit lint || fail`); a clean run — or a run where the