@lorekit/cli 1.69.0 → 1.70.0

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/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

package/src/shared/lessons-view.mjs

@@ -253,6 +253,36 @@ export function diffGroups(offline = {}, remote = {}) {
 // too terse to carry a durable observation (e.g. "yes", "fixed", "todo").
 export const MIN_VALUE_LEN = 12;
 
+// Blank the INTERIOR of fenced code blocks (``` or ~~~ fences) so example content
+// — a lesson documenting an `<!-- MARKER -->` or pasting a ```yaml front-matter
+// sample — is never mistaken for hidden metadata. Such content renders as VISIBLE
+// fenced text, the opposite of the digest-hidden block `hidden-metadata` targets,
+// and `lint` is a CI gate, so a false positive there fails a legitimate lesson.
+// Line positions are preserved (interiors and fence lines become empty) so the
+// heading-anchored checks still see the real document structure. A closing fence
+// is ≥3 of the SAME character as the opener with no trailing info string
+// (CommonMark); an opener may carry an info string (```yaml). Pure.
+function stripFencedCode(value) {
+  let fence = null; // the active fence character (` or ~), or null when outside a block
+  return String(value)
+    .split('\n')
+    .map((line) => {
+      const m = line.match(/^\s*(`{3,}|~{3,})/);
+      if (fence === null) {
+        if (m) {
+          fence = m[1][0];
+          return '';
+        }
+        return line;
+      }
+      if (m && m[1][0] === fence && line.trim().replace(/[`~\s]/g, '') === '') {
+        fence = null;
+      }
+      return '';
+    })
+    .join('\n');
+}
+
 // The lint rule set: each a pure predicate over a normalized entry returning a
 // short reason string when it FIRES, or null when the entry is clean. Kept as
 // discrete named functions so each rule is independently unit-testable and the
@@ -335,6 +365,47 @@ export const LINT_RULES = {
     if (parsed === null || typeof parsed !== 'object') return null; // a bare scalar — short-value's to catch when short, otherwise unjudged.
     return 'value is a JSON object/array with no kind set — it renders as a raw JSON blob in every SessionStart digest; set --kind bus or --kind signal';
   },
+  // A lesson body is markdown for humans — no HTML comment, no front-matter, no
+  // `key=value` header. The `<!-- meta: seen_count=… status=… trigger-context=… -->`
+  // block is a REPUDIATED legacy convention this repo's lorekit-setup skill once
+  // prescribed (still parsed as a read-fallback in `candidates-pure.mjs` /
+  // `commands/invariants.mjs`, and skipped by the digest preview in `core/lessons.mjs`).
+  // It is wrong on the merits: an HTML comment renders to nothing, so a human sees a
+  // lesson starting mid-sentence, while a baked-in `seen_count`/`status`/`trigger`
+  // silently disagrees with the store's own column/tag/field. Conservative like the
+  // other rules — three concrete shapes only, never a fuzzy "looks like metadata":
+  //   1. any HTML comment (`<!--`), the strongest and most common offender;
+  //   2. a body that OPENS with a YAML front-matter block (`---` as the first line);
+  //   3. a machine-metadata header (`meta:`, `seen_count`, `status=`, `expires`,
+  //      `ttl(_days)`, `trigger-context`) appearing BEFORE the first `#` title, so a
+  //      legitimate prose line mid-body never trips it.
+  // All three run against a fence-stripped copy (`stripFencedCode`) so a lesson that
+  // DOCUMENTS one of these shapes inside a code block is never flagged.
+  'hidden-metadata': (e) => {
+    const raw = String(e.value ?? '');
+    if (!raw.trim()) return null; // an empty value is `empty-value`'s to report.
+    const v = stripFencedCode(raw);
+    if (!v.trim()) return null; // nothing outside code fences — no prose metadata to flag.
+    if (v.includes('<!--')) {
+      return "value contains an HTML comment — lesson bodies are pure markdown; move seen_count → the column, status → a status:: tag, trigger → the trigger field";
+    }
+    const lines = v.split('\n');
+    const firstNonEmpty = lines.find((l) => l.trim() !== '');
+    if (firstNonEmpty !== undefined && firstNonEmpty.trim() === '---') {
+      return 'value opens with a front-matter block — lesson bodies carry no front-matter; every stored fact belongs in its own write field';
+    }
+    const headingIdx = lines.findIndex((l) => /^\s*#/.test(l));
+    if (headingIdx > 0) {
+      const metaHeader = lines
+        .slice(0, headingIdx)
+        .filter((l) => l.trim() !== '')
+        .find((l) => /^\s*(meta\b|seen_count\b|status\s*=|expires\b|ttl(?:_days)?\b|trigger[-_]context\b)/i.test(l));
+      if (metaHeader) {
+        return `value has a machine-metadata header before the title ('${metaHeader.trim().slice(0, 40)}') — move it to the store's own fields`;
+      }
+    }
+    return null;
+  },
 };
 
 // Run every lint rule against one normalized entry, returning the findings it