@aitne/daemon 0.1.9 → 0.1.10

package/dist/core/feedback/lesson-format.js

@@ -0,0 +1,194 @@
+/**
+ * Feedback Learning Loop — lesson MD format (FEEDBACK_LEARNING_LOOP_DESIGN.md §3.4).
+ *
+ * A *lesson* is a generalized, injectable directive rendered as a markdown
+ * bullet that extends the existing Learned-Context convention with a
+ * machine-readable trailer:
+ *
+ *   - [2026-06-07] Keep the weekly report's budget section even when spend is
+ *     flat — owner flagged it missing twice.
+ *     <!-- ev=2 kind=correction src=explicit conf=high last=2026-06-07 -->
+ *
+ * Optional `<!-- provisional -->` marks a lesson stored but excluded from
+ * injection until it promotes (§4 step 4).
+ *
+ * This module is pure (no I/O): parse a `## Lessons` section body into typed
+ * {@link Lesson}s and serialize them back byte-stably. It is the shared
+ * vocabulary for the promotion gate, eviction scorer, merge/dedup, and the
+ * consolidation worksheet — the §4 division-of-labour mechanical layer. The
+ * LLM authors *prose*; this code owns the *structure*.
+ */
+export const LESSON_KINDS = new Set([
+    "preference",
+    "correction",
+    "do-more",
+    "do-less",
+    "constraint",
+]);
+export const LESSON_SOURCES = new Set([
+    "explicit",
+    "behavioral",
+    "self_critique",
+]);
+export const LESSON_CONFIDENCES = new Set(["high", "medium", "low"]);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** Bullet entry start: `- [YYYY-MM-DD] …` (rest of the line is prose). */
+const ENTRY_START_RE = /^-\s+\[(\d{4}-\d{2}-\d{2})\]\s?(.*)$/;
+/**
+ * Eviction marker `- [...N … omitted …]` — emitted by the scorer, never a
+ * lesson (its bracket holds `...`, not a date). Skipped on parse so re-reading
+ * a previously-evicted section does not fold the marker text into the
+ * preceding lesson's prose.
+ */
+const OMITTED_MARKER_RE = /^\s*-\s*\[\.\.\./;
+/** Any HTML comment — trailer attrs + the `provisional` marker both ride these. */
+const COMMENT_RE = /<!--([\s\S]*?)-->/g;
+const PROVISIONAL_RE = /<!--\s*provisional\s*-->/i;
+function isDate(value) {
+    return DATE_RE.test(value);
+}
+function coerceKind(value) {
+    return value && LESSON_KINDS.has(value) ? value : "preference";
+}
+function coerceSource(value) {
+    return value && LESSON_SOURCES.has(value)
+        ? value
+        : "behavioral";
+}
+function coerceConf(value) {
+    return value && LESSON_CONFIDENCES.has(value)
+        ? value
+        : "low";
+}
+/** Parse `ev=2 kind=correction src=explicit conf=high last=2026-06-07`. */
+function parseTrailerAttrs(raw) {
+    const out = {};
+    for (const token of raw.trim().split(/\s+/)) {
+        const eq = token.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = token.slice(0, eq);
+        const value = token.slice(eq + 1);
+        if (key.length > 0 && value.length > 0)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Extract a single markdown `## <header>` section body from a file, returning
+ * the lines between the header and the next `## `/`# ` heading (exclusive),
+ * or `null` when the header is absent. CRLF-tolerant.
+ */
+export function extractMarkdownSection(md, header) {
+    const lines = md.split(/\r?\n/);
+    const wanted = `## ${header}`;
+    const start = lines.findIndex((line) => line.trim() === wanted);
+    if (start < 0)
+        return null;
+    const body = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^#{1,2}\s/.test(lines[i]))
+            break;
+        body.push(lines[i]);
+    }
+    return body.join("\n").trim();
+}
+/**
+ * Parse a `## Lessons` section body into typed lessons. Non-lesson lines
+ * (blank lines, the `<!-- scope: … -->` header comment, the `[...N omitted]`
+ * eviction marker, stray prose) are ignored. Continuation lines (indented)
+ * fold into the preceding lesson's prose. Malformed entries degrade to
+ * defaults rather than throwing, so a hand-edited file never crashes the
+ * nightly pass.
+ */
+export function parseLessonsSection(sectionBody) {
+    if (!sectionBody)
+        return [];
+    const lines = sectionBody.split(/\r?\n/);
+    const lessons = [];
+    let current = null;
+    const flush = () => {
+        if (!current)
+            return;
+        const joined = current.buffer.join("\n");
+        const provisional = PROVISIONAL_RE.test(joined);
+        // Merge attrs from every comment in the entry — `provisional` and any
+        // valueless tokens fall out in `parseTrailerAttrs` rather than breaking
+        // the whole trailer match (a hand-edited file never crashes the pass).
+        const attrs = {};
+        for (const match of joined.matchAll(COMMENT_RE)) {
+            Object.assign(attrs, parseTrailerAttrs(match[1]));
+        }
+        // Strip every HTML comment (trailer + provisional marker) from prose.
+        const text = joined
+            .replace(/<!--[\s\S]*?-->/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        const evNum = Number(attrs.ev);
+        const ev = Number.isFinite(evNum) && evNum > 0 ? evNum : 1;
+        const last = attrs.last && isDate(attrs.last) ? attrs.last : current.date;
+        lessons.push({
+            date: current.date,
+            text,
+            ev,
+            kind: coerceKind(attrs.kind),
+            src: coerceSource(attrs.src),
+            conf: coerceConf(attrs.conf),
+            last,
+            provisional,
+        });
+        current = null;
+    };
+    for (const line of lines) {
+        const startMatch = ENTRY_START_RE.exec(line);
+        if (startMatch) {
+            flush();
+            current = { date: startMatch[1], buffer: [startMatch[2]] };
+            continue;
+        }
+        if (OMITTED_MARKER_RE.test(line)) {
+            // The eviction marker terminates the current lesson and is not itself a
+            // lesson — neither a continuation nor a new entry.
+            flush();
+            continue;
+        }
+        if (current && (line.startsWith("  ") || line.trim().length > 0)) {
+            // Continuation of the current lesson (indented, or a trailer comment
+            // the author placed on its own non-indented line).
+            current.buffer.push(line.trim());
+        }
+        else if (current) {
+            // Blank line ends the current lesson.
+            flush();
+        }
+    }
+    flush();
+    return lessons;
+}
+/**
+ * Render one lesson as a markdown bullet with its trailer. Prose stays on the
+ * first line; the trailer follows on a 2-space-indented continuation line so
+ * it survives `trimBulletEntries` / `clearEntriesBefore` continuation rules.
+ */
+export function formatLesson(lesson) {
+    const trailer = `<!-- ev=${lesson.ev} kind=${lesson.kind} src=${lesson.src} ` +
+        `conf=${lesson.conf} last=${lesson.last} -->`;
+    const provisional = lesson.provisional ? " <!-- provisional -->" : "";
+    return `- [${lesson.date}] ${lesson.text}\n  ${trailer}${provisional}`;
+}
+/**
+ * Render a full `## Lessons` section: the `<!-- scope: … -->` header comment
+ * (carrying the cap for at-a-glance review), the lesson bullets, and an
+ * optional eviction marker. `scopeLabel` is the {@link formatScope} string.
+ */
+export function formatLessonsSection(lessons, opts) {
+    const header = `<!-- scope: ${opts.scopeLabel} · cap: ${opts.capBytes}B · ${opts.maxEntries} entries -->`;
+    const parts = [header, ...lessons.map((lesson) => formatLesson(lesson))];
+    if (opts.omittedMarker)
+        parts.push(opts.omittedMarker);
+    return parts.join("\n");
+}
+/** UTF-8 byte length of a serialized lessons section — the cap unit (§6). */
+export function lessonsSectionByteLength(lessons, opts) {
+    return Buffer.byteLength(formatLessonsSection(lessons, opts), "utf-8");
+}

package/dist/core/feedback/lesson-injection.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Feedback Learning Loop — Stage 3 inject renderer (FEEDBACK_LEARNING_LOOP_DESIGN.md §5/§6).
+ *
+ * Renders the `<agent_lessons>` block `ContextBuilder` pushes onto DM /
+ * notify-deciding turns. Pure logic, no I/O — the FS read (the lessons file)
+ * lives in the coverage-excluded builder; this module owns the *structure* and
+ * the *cap*, and is in the 100%-covered `core/feedback/*` subset (§8).
+ *
+ * Three variants, matching the §5/§6 split — all pack the highest-signal lessons
+ * under their cap via one shared {@link packByScore} core, differing only in the
+ * wrapper tag, preamble, cap unit, entry cap, and whether an over-cap is an
+ * operability signal:
+ *
+ *  - **global** (DM + review cadences + defined-agent runs) — emit every
+ *    *active* (non-provisional) lesson from `policies/agent-lessons.md` when the
+ *    body fits the cap. Over cap the block **degrades to the top-N lessons by
+ *    score** (v1.5 §11.6) and the builder warns: the cap stays a hard,
+ *    non-bypassable guarantee (the emitted body never exceeds it), but the agent
+ *    keeps the highest-signal lessons instead of losing all of them. A degrade
+ *    only happens if consolidation failed to pre-cap the file, so it is an
+ *    operability signal (`overflow`), not a routine path.
+ *  - **self** (Phase 4 — any run bound to an Agent slug) — identical render +
+ *    degrade discipline to global, but the source is the per-agent
+ *    `policies/agents/<slug>/lessons.md` and the wrapper is
+ *    `<agent_lessons scope="self">` with a self-facing preamble. Capped at
+ *    `feedbackLessonMaxBytesPerAgent`; over-cap degrades + warns exactly like
+ *    global. Selected via `opts.selfScope`.
+ *  - **slim** (hourly notify turn) — top-N by eviction score, greedily packed
+ *    so the *whole* block stays under the hard 2048-byte budget (§6). Tail
+ *    dropping is routine here (tight hourly budget), so the slim path never
+ *    reports `overflow`; it just drops the lowest-signal tail.
+ *
+ * Provisional lessons are excluded from injection (§4 step 4) — they are stored
+ * for corroboration but must not yet bind behaviour. The machine-readable
+ * trailers (`<!-- ev=… -->`) are dropped: the agent consumes the directive
+ * prose, not the consolidator's bookkeeping.
+ */
+/**
+ * Hard inject-time byte cap for the slim hourly notify-discipline variant (§6
+ * table: "slim notify-discipline subset injected to hourly_check · hard 2048 at
+ * inject"). Exported so the builder and tests share one constant.
+ */
+export declare const AGENT_LESSONS_SLIM_CAP_BYTES = 2048;
+/**
+ * Belt-and-braces entry cap for the slim variant: the byte cap is the binding
+ * constraint, but a small entry cap keeps the hourly turn focused on the
+ * highest-signal lessons even if they are individually tiny.
+ */
+export declare const AGENT_LESSONS_SLIM_MAX_ENTRIES = 12;
+export interface AgentLessonsBlockResult {
+    /** The `<agent_lessons>`-wrapped block, or `null` when nothing is injected. */
+    block: string | null;
+    /**
+     * Set **only** on the global path when the full body exceeded `capBytes` and
+     * lessons had to be dropped to fit — the builder logs a warning.
+     *  - `bytes` is the full (over-cap) body size that triggered the degrade;
+     *  - `dropped` is how many lessons were left out (all of them when not even
+     *    the single highest-scored lesson fits, in which case `block` is `null`).
+     *
+     * `null` on the slim path (tail-dropping there is routine, not a warning
+     * condition) and whenever everything fit. The cap is never breached either
+     * way: this signals a degrade, not a cap bypass.
+     */
+    overflow: {
+        bytes: number;
+        cap: number;
+        dropped: number;
+    } | null;
+}
+export interface RenderAgentLessonsOptions {
+    /** Defensive byte cap for the rendered body (global/self) / whole block (slim). */
+    capBytes: number;
+    /** Slim hourly variant: top-N by score, packed under the hard byte cap. */
+    slim: boolean;
+    /** ISO timestamp used to score lessons for ranking + degrade. */
+    nowIso: string;
+    /** Override the slim entry cap (defaults to {@link AGENT_LESSONS_SLIM_MAX_ENTRIES}). */
+    maxSlimEntries?: number;
+    /**
+     * Phase 4 — render the per-agent (`agent:<slug>`) block: wrap as
+     * `<agent_lessons scope="self">` with the self preamble, same body cap +
+     * degrade discipline as global. Ignored when {@link RenderAgentLessonsOptions.slim}
+     * is set (the slim variant is global-only by construction).
+     */
+    selfScope?: boolean;
+}
+/**
+ * Render the `<agent_lessons>` block for a surface, or `null` when there is
+ * nothing to inject (no file, no `## Lessons` section, no active lessons, or —
+ * global/self path only — not even the single highest-scored lesson fits the
+ * cap). When the global/self body is over cap but some lessons fit, the block
+ * degrades to the top-N by score and `overflow` is set so the caller can warn.
+ *
+ * Variant selection: `slim` → the hourly notify block; else `selfScope` → the
+ * per-agent `<agent_lessons scope="self">` block; else the global block. `slim`
+ * and `selfScope` are mutually exclusive by construction (slim wins).
+ */
+export declare function renderAgentLessonsBlock(fileMd: string | null, opts: RenderAgentLessonsOptions): AgentLessonsBlockResult;

package/dist/core/feedback/lesson-injection.js

@@ -0,0 +1,159 @@
+/**
+ * Feedback Learning Loop — Stage 3 inject renderer (FEEDBACK_LEARNING_LOOP_DESIGN.md §5/§6).
+ *
+ * Renders the `<agent_lessons>` block `ContextBuilder` pushes onto DM /
+ * notify-deciding turns. Pure logic, no I/O — the FS read (the lessons file)
+ * lives in the coverage-excluded builder; this module owns the *structure* and
+ * the *cap*, and is in the 100%-covered `core/feedback/*` subset (§8).
+ *
+ * Three variants, matching the §5/§6 split — all pack the highest-signal lessons
+ * under their cap via one shared {@link packByScore} core, differing only in the
+ * wrapper tag, preamble, cap unit, entry cap, and whether an over-cap is an
+ * operability signal:
+ *
+ *  - **global** (DM + review cadences + defined-agent runs) — emit every
+ *    *active* (non-provisional) lesson from `policies/agent-lessons.md` when the
+ *    body fits the cap. Over cap the block **degrades to the top-N lessons by
+ *    score** (v1.5 §11.6) and the builder warns: the cap stays a hard,
+ *    non-bypassable guarantee (the emitted body never exceeds it), but the agent
+ *    keeps the highest-signal lessons instead of losing all of them. A degrade
+ *    only happens if consolidation failed to pre-cap the file, so it is an
+ *    operability signal (`overflow`), not a routine path.
+ *  - **self** (Phase 4 — any run bound to an Agent slug) — identical render +
+ *    degrade discipline to global, but the source is the per-agent
+ *    `policies/agents/<slug>/lessons.md` and the wrapper is
+ *    `<agent_lessons scope="self">` with a self-facing preamble. Capped at
+ *    `feedbackLessonMaxBytesPerAgent`; over-cap degrades + warns exactly like
+ *    global. Selected via `opts.selfScope`.
+ *  - **slim** (hourly notify turn) — top-N by eviction score, greedily packed
+ *    so the *whole* block stays under the hard 2048-byte budget (§6). Tail
+ *    dropping is routine here (tight hourly budget), so the slim path never
+ *    reports `overflow`; it just drops the lowest-signal tail.
+ *
+ * Provisional lessons are excluded from injection (§4 step 4) — they are stored
+ * for corroboration but must not yet bind behaviour. The machine-readable
+ * trailers (`<!-- ev=… -->`) are dropped: the agent consumes the directive
+ * prose, not the consolidator's bookkeeping.
+ */
+import { extractMarkdownSection, parseLessonsSection, } from "./lesson-format.js";
+import { scoreLesson } from "./eviction-scorer.js";
+/**
+ * Hard inject-time byte cap for the slim hourly notify-discipline variant (§6
+ * table: "slim notify-discipline subset injected to hourly_check · hard 2048 at
+ * inject"). Exported so the builder and tests share one constant.
+ */
+export const AGENT_LESSONS_SLIM_CAP_BYTES = 2048;
+/**
+ * Belt-and-braces entry cap for the slim variant: the byte cap is the binding
+ * constraint, but a small entry cap keeps the hourly turn focused on the
+ * highest-signal lessons even if they are individually tiny.
+ */
+export const AGENT_LESSONS_SLIM_MAX_ENTRIES = 12;
+const GLOBAL_STYLE = {
+    openTag: "<agent_lessons>",
+    preamble: "Lessons calibrated from past owner feedback and your own reviews. Treat each " +
+        "as a standing directive and prefer it over your defaults when they conflict.",
+};
+const SELF_STYLE = {
+    openTag: '<agent_lessons scope="self">',
+    preamble: "Lessons calibrated specifically from feedback on THIS agent's own past " +
+        "output. Treat each as a standing directive for your work and prefer it over " +
+        "your defaults when they conflict.",
+};
+const SLIM_PREAMBLE = "Your highest-signal operating lessons, calibrated from past feedback. Weigh " +
+    "these before deciding whether to notify the owner.";
+/** Parse the `## Lessons` section and keep only injectable (active) lessons. */
+function activeLessons(fileMd) {
+    const section = extractMarkdownSection(fileMd, "Lessons");
+    if (!section)
+        return [];
+    return parseLessonsSection(section).filter((lesson) => !lesson.provisional && lesson.text.length > 0);
+}
+/** One lesson as an agent-facing bullet (trailer + date stripped). */
+function bulletFor(lesson) {
+    return `- ${lesson.text}`;
+}
+function wrap(style, bullets) {
+    return [style.openTag, style.preamble, ...bullets, "</agent_lessons>"].join("\n");
+}
+/**
+ * Greedily keep the highest-scored lessons whose serialized form — produced by
+ * `render`, the cap-measured unit — stays within `capBytes`, up to `maxEntries`.
+ * Returns the kept bullets (highest-score-first) and how many lessons dropped.
+ *
+ * Strict score-prefix: stops at the first lesson that would overflow — a
+ * lower-scored shorter tail is never swapped in, since that would violate
+ * "top-N by score". Scoring is the same `scoreLesson` consolidation eviction
+ * uses, so inject-time ranking matches on-disk ranking. Measuring and keeping
+ * the same `bullet` value guarantees what was size-checked is exactly what
+ * lands in the block.
+ */
+function packByScore(lessons, nowIso, capBytes, maxEntries, render) {
+    const ranked = [...lessons].sort((a, b) => scoreLesson(b, nowIso) - scoreLesson(a, nowIso));
+    const kept = [];
+    for (const lesson of ranked) {
+        if (kept.length >= maxEntries)
+            break;
+        const bullet = bulletFor(lesson);
+        if (Buffer.byteLength(render([...kept, bullet]), "utf-8") > capBytes)
+            break;
+        kept.push(bullet);
+    }
+    return { kept, dropped: ranked.length - kept.length };
+}
+function renderBody(lessons, capBytes, nowIso, style) {
+    // Cap on the rendered body — matches the `<management_rules>` precedent
+    // (check the content bytes, then wrap unconditionally). The wrapper tag /
+    // preamble are the only per-variant difference between global and self.
+    const bodyBytes = Buffer.byteLength(lessons.map(bulletFor).join("\n"), "utf-8");
+    if (bodyBytes <= capBytes) {
+        return { block: wrap(style, lessons.map(bulletFor)), overflow: null };
+    }
+    // Over cap → graceful degradation (v1.5 §11.6): keep the highest-scored
+    // lessons whose body still fits and warn, rather than dropping all of them.
+    // The cap stays a hard, non-bypassable guarantee (the emitted body never
+    // exceeds it); consolidation should have pre-capped the file, so a degrade
+    // here is an operability signal the builder logs.
+    const { kept, dropped } = packByScore(lessons, nowIso, capBytes, Number.POSITIVE_INFINITY, (bullets) => bullets.join("\n"));
+    const overflow = { bytes: bodyBytes, cap: capBytes, dropped };
+    // Even the single highest-scored bullet can exceed the cap → empty kept set.
+    if (kept.length === 0)
+        return { block: null, overflow };
+    return { block: wrap(style, kept), overflow };
+}
+function renderSlim(lessons, opts) {
+    const maxEntries = opts.maxSlimEntries ?? AGENT_LESSONS_SLIM_MAX_ENTRIES;
+    // Measure the *whole* block so the hard 2048 budget covers preamble + tags,
+    // not just the bullets. Tail-dropping is routine on the tight hourly turn, so
+    // the slim path never reports `overflow`. Slim is global-only — always the
+    // plain `<agent_lessons>` wrapper with the notify-discipline preamble.
+    const slimStyle = {
+        openTag: GLOBAL_STYLE.openTag,
+        preamble: SLIM_PREAMBLE,
+    };
+    const { kept } = packByScore(lessons, opts.nowIso, opts.capBytes, maxEntries, (bullets) => wrap(slimStyle, bullets));
+    if (kept.length === 0)
+        return { block: null, overflow: null };
+    return { block: wrap(slimStyle, kept), overflow: null };
+}
+/**
+ * Render the `<agent_lessons>` block for a surface, or `null` when there is
+ * nothing to inject (no file, no `## Lessons` section, no active lessons, or —
+ * global/self path only — not even the single highest-scored lesson fits the
+ * cap). When the global/self body is over cap but some lessons fit, the block
+ * degrades to the top-N by score and `overflow` is set so the caller can warn.
+ *
+ * Variant selection: `slim` → the hourly notify block; else `selfScope` → the
+ * per-agent `<agent_lessons scope="self">` block; else the global block. `slim`
+ * and `selfScope` are mutually exclusive by construction (slim wins).
+ */
+export function renderAgentLessonsBlock(fileMd, opts) {
+    if (!fileMd)
+        return { block: null, overflow: null };
+    const lessons = activeLessons(fileMd);
+    if (lessons.length === 0)
+        return { block: null, overflow: null };
+    if (opts.slim)
+        return renderSlim(lessons, opts);
+    return renderBody(lessons, opts.capBytes, opts.nowIso, opts.selfScope ? SELF_STYLE : GLOBAL_STYLE);
+}

package/dist/core/feedback/lesson-merge.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Feedback Learning Loop — mechanical merge / dedup (FEEDBACK_LEARNING_LOOP_DESIGN.md §4 step 3, §6).
+ *
+ * The *mechanical* half of "merge, don't append": group incoming signals by a
+ * normalised summary so identical reports collapse into one candidate, and
+ * collapse near-duplicate existing lessons (summing their `ev`) before the
+ * eviction scorer runs (§6: "Near-duplicates are merged … before eviction is
+ * even considered").
+ *
+ * The *semantic* half — judging whether a candidate matches an existing
+ * lesson's *intent* and phrasing the generalization — is the LLM's job (§4
+ * division of labour). This module never paraphrases; it only collapses exact
+ * normalised-text matches, which is safe to do deterministically.
+ */
+import type { Lesson } from "./lesson-format.js";
+/**
+ * Normalise a summary for mechanical equality: lowercase, strip punctuation,
+ * collapse whitespace. Two signals/lessons with the same normalised form are
+ * treated as the same candidate. Conservative — only *identical* phrasings
+ * collapse; anything semantic is left to the LLM.
+ */
+export declare function normalizeSummary(summary: string): string;
+export interface SignalLike {
+    id: number;
+    summary: string;
+}
+export interface SignalGroup<T extends SignalLike> {
+    /** Normalised-summary key shared by every member. */
+    key: string;
+    /** Representative (first-seen) raw summary, for display. */
+    summary: string;
+    members: T[];
+}
+/**
+ * Group signals by normalised summary, preserving first-seen order for both
+ * the groups and their members. Empty / whitespace-only summaries are kept
+ * under a stable empty key rather than dropped, so no signal id is lost from
+ * the consume set.
+ */
+export declare function groupSignalsBySummary<T extends SignalLike>(signals: ReadonlyArray<T>): SignalGroup<T>[];
+/**
+ * Collapse near-duplicate lessons (identical normalised text) into one, summing
+ * `ev`, keeping the earliest `date`, the latest `last`, the max confidence, the
+ * strongest `kind` (constraint outranks a softer kind), and OR-ing
+ * `provisional` to `false` if any duplicate is active. Order is stable: the
+ * first occurrence's position is retained.
+ *
+ * Deterministic and lossless on `ev` — the summed evidence flows straight into
+ * the eviction score so a merged lesson is *harder* to evict, never easier.
+ */
+export declare function dedupeLessons(lessons: ReadonlyArray<Lesson>): Lesson[];

package/dist/core/feedback/lesson-merge.js

@@ -0,0 +1,88 @@
+/**
+ * Feedback Learning Loop — mechanical merge / dedup (FEEDBACK_LEARNING_LOOP_DESIGN.md §4 step 3, §6).
+ *
+ * The *mechanical* half of "merge, don't append": group incoming signals by a
+ * normalised summary so identical reports collapse into one candidate, and
+ * collapse near-duplicate existing lessons (summing their `ev`) before the
+ * eviction scorer runs (§6: "Near-duplicates are merged … before eviction is
+ * even considered").
+ *
+ * The *semantic* half — judging whether a candidate matches an existing
+ * lesson's *intent* and phrasing the generalization — is the LLM's job (§4
+ * division of labour). This module never paraphrases; it only collapses exact
+ * normalised-text matches, which is safe to do deterministically.
+ */
+/**
+ * Normalise a summary for mechanical equality: lowercase, strip punctuation,
+ * collapse whitespace. Two signals/lessons with the same normalised form are
+ * treated as the same candidate. Conservative — only *identical* phrasings
+ * collapse; anything semantic is left to the LLM.
+ */
+export function normalizeSummary(summary) {
+    return summary
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Group signals by normalised summary, preserving first-seen order for both
+ * the groups and their members. Empty / whitespace-only summaries are kept
+ * under a stable empty key rather than dropped, so no signal id is lost from
+ * the consume set.
+ */
+export function groupSignalsBySummary(signals) {
+    const order = [];
+    const byKey = new Map();
+    for (const signal of signals) {
+        const key = normalizeSummary(signal.summary);
+        let group = byKey.get(key);
+        if (!group) {
+            group = { key, summary: signal.summary, members: [] };
+            byKey.set(key, group);
+            order.push(key);
+        }
+        group.members.push(signal);
+    }
+    return order.map((key) => byKey.get(key));
+}
+const CONF_RANK = {
+    high: 3,
+    medium: 2,
+    low: 1,
+};
+/**
+ * Collapse near-duplicate lessons (identical normalised text) into one, summing
+ * `ev`, keeping the earliest `date`, the latest `last`, the max confidence, the
+ * strongest `kind` (constraint outranks a softer kind), and OR-ing
+ * `provisional` to `false` if any duplicate is active. Order is stable: the
+ * first occurrence's position is retained.
+ *
+ * Deterministic and lossless on `ev` — the summed evidence flows straight into
+ * the eviction score so a merged lesson is *harder* to evict, never easier.
+ */
+export function dedupeLessons(lessons) {
+    const order = [];
+    const byKey = new Map();
+    for (const lesson of lessons) {
+        const key = normalizeSummary(lesson.text);
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, { ...lesson });
+            order.push(key);
+            continue;
+        }
+        existing.ev += lesson.ev;
+        if (lesson.date < existing.date)
+            existing.date = lesson.date;
+        if (lesson.last > existing.last)
+            existing.last = lesson.last;
+        if (CONF_RANK[lesson.conf] > CONF_RANK[existing.conf]) {
+            existing.conf = lesson.conf;
+        }
+        if (lesson.kind === "constraint")
+            existing.kind = "constraint";
+        existing.provisional = existing.provisional && lesson.provisional;
+    }
+    return order.map((key) => byKey.get(key));
+}

package/dist/core/feedback/lesson-store-overview.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Feedback Learning Loop — lesson-store overview (FEEDBACK_LEARNING_LOOP_DESIGN.md §9 Phase 5).
+ *
+ * The pure, deterministic half of the `GET /api/feedback/lessons` dashboard
+ * surface. The route (coverage-excluded — it does the FS enumeration) hands
+ * each lesson file's raw contents to {@link summarizeLessonStore}, which parses
+ * the `## Lessons` section and reports the cap-utilisation metrics the
+ * "view/edit lessons and tune caps/threshold" settings page renders:
+ * byte size vs. cap, entry count vs. cap, active vs. provisional split, and
+ * whether the store is currently over either cap.
+ *
+ * Mirrors the §4 division of labour: the byte/entry accounting is mechanical
+ * (here, 100% covered), while the route owns only the FS read + JSON assembly.
+ */
+export interface LessonStoreSummary {
+    /** UTF-8 byte size of the whole file (the cap unit, §6). */
+    bytes: number;
+    /** Per-scope byte cap. */
+    capBytes: number;
+    /** Total parsed lessons (active + provisional). */
+    entries: number;
+    /** Per-scope entry cap. */
+    maxEntries: number;
+    /** Injectable (promoted) lessons — the ones that actually reach a prompt. */
+    active: number;
+    /** Stored-but-not-yet-injected lessons awaiting corroboration (§4 step 4). */
+    provisional: number;
+    /** True when the file exceeds its byte cap or its entry cap. */
+    overCap: boolean;
+}
+/**
+ * Summarise one lesson store from its raw file contents. A file with no
+ * `## Lessons` section (or an empty one) reports zero entries — never throws,
+ * so a hand-edited or partially-written file degrades to "empty store" rather
+ * than breaking the overview. `bytes` is measured against the *whole* file
+ * because that is what the consolidation cap and the eviction scorer both
+ * guard, matching what lands on disk.
+ */
+export declare function summarizeLessonStore(fileMd: string, caps: {
+    capBytes: number;
+    maxEntries: number;
+}): LessonStoreSummary;

package/dist/core/feedback/lesson-store-overview.js

@@ -0,0 +1,38 @@
+/**
+ * Feedback Learning Loop — lesson-store overview (FEEDBACK_LEARNING_LOOP_DESIGN.md §9 Phase 5).
+ *
+ * The pure, deterministic half of the `GET /api/feedback/lessons` dashboard
+ * surface. The route (coverage-excluded — it does the FS enumeration) hands
+ * each lesson file's raw contents to {@link summarizeLessonStore}, which parses
+ * the `## Lessons` section and reports the cap-utilisation metrics the
+ * "view/edit lessons and tune caps/threshold" settings page renders:
+ * byte size vs. cap, entry count vs. cap, active vs. provisional split, and
+ * whether the store is currently over either cap.
+ *
+ * Mirrors the §4 division of labour: the byte/entry accounting is mechanical
+ * (here, 100% covered), while the route owns only the FS read + JSON assembly.
+ */
+import { extractMarkdownSection, parseLessonsSection, } from "./lesson-format.js";
+/**
+ * Summarise one lesson store from its raw file contents. A file with no
+ * `## Lessons` section (or an empty one) reports zero entries — never throws,
+ * so a hand-edited or partially-written file degrades to "empty store" rather
+ * than breaking the overview. `bytes` is measured against the *whole* file
+ * because that is what the consolidation cap and the eviction scorer both
+ * guard, matching what lands on disk.
+ */
+export function summarizeLessonStore(fileMd, caps) {
+    const sectionBody = extractMarkdownSection(fileMd, "Lessons");
+    const lessons = sectionBody ? parseLessonsSection(sectionBody) : [];
+    const provisional = lessons.filter((lesson) => lesson.provisional).length;
+    const bytes = Buffer.byteLength(fileMd, "utf-8");
+    return {
+        bytes,
+        capBytes: caps.capBytes,
+        entries: lessons.length,
+        maxEntries: caps.maxEntries,
+        active: lessons.length - provisional,
+        provisional,
+        overCap: bytes > caps.capBytes || lessons.length > caps.maxEntries,
+    };
+}