@aitne/daemon 0.1.9 → 0.1.11

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,46 @@
+/**
+ * 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 on-disk `## Lessons` section (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` measures the on-disk `## Lessons`
+ * section body — the §6 cap unit (`lessonsSectionByteLength` in
+ * lesson-format.ts) the eviction scorer and the nightly worksheet's
+ * `over_cap` enforce. Measuring the whole file here previously reported a
+ * permanently-stuck `overCap: true` in the band where the section fit the
+ * cap but frontmatter + heading overhead pushed the file past it — a state
+ * no enforcement actor would ever clear.
+ */
+export declare function summarizeLessonStore(fileMd: string, caps: {
+    capBytes: number;
+    maxEntries: number;
+}): LessonStoreSummary;

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

@@ -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.
+ */
+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` measures the on-disk `## Lessons`
+ * section body — the §6 cap unit (`lessonsSectionByteLength` in
+ * lesson-format.ts) the eviction scorer and the nightly worksheet's
+ * `over_cap` enforce. Measuring the whole file here previously reported a
+ * permanently-stuck `overCap: true` in the band where the section fit the
+ * cap but frontmatter + heading overhead pushed the file past it — a state
+ * no enforcement actor would ever clear.
+ */
+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 = sectionBody ? Buffer.byteLength(sectionBody, "utf-8") : 0;
+    return {
+        bytes,
+        capBytes: caps.capBytes,
+        entries: lessons.length,
+        maxEntries: caps.maxEntries,
+        active: lessons.length - provisional,
+        provisional,
+        overCap: bytes > caps.capBytes || lessons.length > caps.maxEntries,
+    };
+}

package/dist/core/feedback/promotion-gate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Feedback Learning Loop — promotion gate (FEEDBACK_LEARNING_LOOP_DESIGN.md §4 step 4).
+ *
+ * Decides whether a candidate lesson (one or more corroborating signals) is
+ * *active / injectable* or stays *provisional*. This is the deterministic
+ * "globally optimized, not single-shot" gate (requirement #4): the LLM groups
+ * signals by intent (semantic), but the promote/hold decision is pure code so
+ * the model never decides the threshold.
+ *
+ * Two hard rules kill the §3.5.1 sign-inversion failure mode at the gate:
+ *   1. `ignored` carries `valence='neutral'` and weight 0.25 — silence is weak
+ *      corroboration, never disapproval, and can never *flip a lesson negative*.
+ *   2. `ignored` is **non-initiating**: a candidate made *only* of `ignored`
+ *      signals never promotes, regardless of weighted sum. An ignore can
+ *      strengthen an explicit/corrected lesson; it can never start one.
+ */
+import type { FeedbackSignalSource, FeedbackSignalValence } from "../../db/feedback-signals-store.js";
+/** Minimal signal shape the gate scores — a projection of `feedback_signals`. */
+export interface GateSignal {
+    source: FeedbackSignalSource;
+    valence: FeedbackSignalValence | null;
+}
+/**
+ * Per-signal evidence weight (§3.5.1 / §4 step 4):
+ *   explicit | corrected = 1.0 · self_critique | replied | acted = 0.5 · ignored = 0.25
+ *
+ * Derived from `(source, valence)` only — `valence` already encodes the
+ * behavioral reaction (corrected→correction, ignored→neutral,
+ * replied/acted→positive), so the gate needs no `evidence_json` lookup.
+ * Checked in priority order: an authoritative directive (explicit source or a
+ * correction) outranks everything; only the *behavioral* `ignored` reaction
+ * (see {@link isIgnoredSignal}) drops to 0.25 — a neutral valence on an
+ * `explicit`/`self_critique` row is a deliberate signal, not silence, and keeps
+ * the 0.5 (or 1.0, for explicit) authoritative weight.
+ */
+export declare function signalWeight(signal: GateSignal): number;
+/**
+ * `ignored` is the §3.5.1 behavioral notification-elapsed reaction: a
+ * `behavioral` signal carrying `valence='neutral'`. It drives the
+ * non-initiating / never-negative rule. A *neutral* valence on an `explicit`
+ * or `self_critique` row is NOT an ignore — it is an authoritative/deliberate
+ * signal that merely lacks a positive/negative tilt — so it must not inherit
+ * the 0.25 weight or the non-initiating treatment. Scoping the check to
+ * `behavioral` keeps this consistent with {@link signalWeight}, which already
+ * treats an explicit-neutral row as authoritative (1.0).
+ */
+export declare function isIgnoredSignal(signal: GateSignal): boolean;
+/** An authoritative owner directive — promotes on first occurrence. */
+export declare function isExplicitDirective(signal: GateSignal): boolean;
+/** Weighted evidence sum across a candidate's contributing signals. */
+export declare function computeWeightedEvidence(signals: ReadonlyArray<GateSignal>): number;
+export type PromotionReason = "explicit-directive" | "evidence-threshold" | "below-threshold" | "ignored-non-initiating" | "no-signals";
+export interface PromotionVerdict {
+    /** Active & injectable when true; provisional otherwise. */
+    promotable: boolean;
+    /** Stored-but-excluded-from-injection marker (`<!-- provisional -->`). */
+    provisional: boolean;
+    /** `high` if any explicit/corrected; `medium` at threshold; else `low`. */
+    conf: "high" | "medium" | "low";
+    weightedEv: number;
+    reason: PromotionReason;
+}
+/**
+ * Evaluate the promotion gate for a candidate's contributing signals.
+ *
+ * @param threshold weighted-evidence bar for behavioral/self_critique
+ *   (`feedbackPromotionThreshold`, default 2).
+ */
+export declare function evaluatePromotion(signals: ReadonlyArray<GateSignal>, threshold: number): PromotionVerdict;

package/dist/core/feedback/promotion-gate.js

@@ -0,0 +1,117 @@
+/**
+ * Feedback Learning Loop — promotion gate (FEEDBACK_LEARNING_LOOP_DESIGN.md §4 step 4).
+ *
+ * Decides whether a candidate lesson (one or more corroborating signals) is
+ * *active / injectable* or stays *provisional*. This is the deterministic
+ * "globally optimized, not single-shot" gate (requirement #4): the LLM groups
+ * signals by intent (semantic), but the promote/hold decision is pure code so
+ * the model never decides the threshold.
+ *
+ * Two hard rules kill the §3.5.1 sign-inversion failure mode at the gate:
+ *   1. `ignored` carries `valence='neutral'` and weight 0.25 — silence is weak
+ *      corroboration, never disapproval, and can never *flip a lesson negative*.
+ *   2. `ignored` is **non-initiating**: a candidate made *only* of `ignored`
+ *      signals never promotes, regardless of weighted sum. An ignore can
+ *      strengthen an explicit/corrected lesson; it can never start one.
+ */
+/**
+ * Per-signal evidence weight (§3.5.1 / §4 step 4):
+ *   explicit | corrected = 1.0 · self_critique | replied | acted = 0.5 · ignored = 0.25
+ *
+ * Derived from `(source, valence)` only — `valence` already encodes the
+ * behavioral reaction (corrected→correction, ignored→neutral,
+ * replied/acted→positive), so the gate needs no `evidence_json` lookup.
+ * Checked in priority order: an authoritative directive (explicit source or a
+ * correction) outranks everything; only the *behavioral* `ignored` reaction
+ * (see {@link isIgnoredSignal}) drops to 0.25 — a neutral valence on an
+ * `explicit`/`self_critique` row is a deliberate signal, not silence, and keeps
+ * the 0.5 (or 1.0, for explicit) authoritative weight.
+ */
+export function signalWeight(signal) {
+    if (signal.source === "explicit")
+        return 1.0;
+    if (signal.valence === "correction")
+        return 1.0;
+    if (isIgnoredSignal(signal))
+        return 0.25;
+    return 0.5;
+}
+/**
+ * `ignored` is the §3.5.1 behavioral notification-elapsed reaction: a
+ * `behavioral` signal carrying `valence='neutral'`. It drives the
+ * non-initiating / never-negative rule. A *neutral* valence on an `explicit`
+ * or `self_critique` row is NOT an ignore — it is an authoritative/deliberate
+ * signal that merely lacks a positive/negative tilt — so it must not inherit
+ * the 0.25 weight or the non-initiating treatment. Scoping the check to
+ * `behavioral` keeps this consistent with {@link signalWeight}, which already
+ * treats an explicit-neutral row as authoritative (1.0).
+ */
+export function isIgnoredSignal(signal) {
+    return signal.source === "behavioral" && signal.valence === "neutral";
+}
+/** An authoritative owner directive — promotes on first occurrence. */
+export function isExplicitDirective(signal) {
+    return signal.source === "explicit" || signal.valence === "correction";
+}
+/** Weighted evidence sum across a candidate's contributing signals. */
+export function computeWeightedEvidence(signals) {
+    return signals.reduce((sum, signal) => sum + signalWeight(signal), 0);
+}
+/**
+ * Evaluate the promotion gate for a candidate's contributing signals.
+ *
+ * @param threshold weighted-evidence bar for behavioral/self_critique
+ *   (`feedbackPromotionThreshold`, default 2).
+ */
+export function evaluatePromotion(signals, threshold) {
+    const weightedEv = computeWeightedEvidence(signals);
+    if (signals.length === 0) {
+        return {
+            promotable: false,
+            provisional: true,
+            conf: "low",
+            weightedEv,
+            reason: "no-signals",
+        };
+    }
+    // Rule 2: an ignored-only candidate is non-initiating — never promotes,
+    // regardless of weighted sum (two coincidental busy-morning ignores cannot
+    // teach "stop notifying about X").
+    if (signals.every(isIgnoredSignal)) {
+        return {
+            promotable: false,
+            provisional: true,
+            conf: "low",
+            weightedEv,
+            reason: "ignored-non-initiating",
+        };
+    }
+    // An explicit owner directive (or any correction) is authoritative →
+    // promote on first occurrence with high confidence.
+    if (signals.some(isExplicitDirective)) {
+        return {
+            promotable: true,
+            provisional: false,
+            conf: "high",
+            weightedEv,
+            reason: "explicit-directive",
+        };
+    }
+    // Behavioral / self_critique corroboration: promote at the weighted bar.
+    if (weightedEv >= threshold) {
+        return {
+            promotable: true,
+            provisional: false,
+            conf: "medium",
+            weightedEv,
+            reason: "evidence-threshold",
+        };
+    }
+    return {
+        promotable: false,
+        provisional: true,
+        conf: "low",
+        weightedEv,
+        reason: "below-threshold",
+    };
+}

package/dist/core/feedback/regeneralization-prep.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Feedback Learning Loop — monthly re-generalization pre-step
+ * (FEEDBACK_LEARNING_LOOP_DESIGN.md §4 "Monthly re-generalization", Phase 5).
+ *
+ * The deterministic, daemon-side half of the *monthly* collapse. Where the
+ * nightly evening-review pre-step (`consolidation-prep.ts`) folds unconsumed
+ * *signals* into lessons, the monthly pass re-reads the *already-consolidated*
+ * lesson stores and surfaces them so the LLM can collapse several specific
+ * lessons that share a theme into one higher-level principle — e.g. three
+ * "shorter mail summary" / "shorter standup" / "shorter report" lessons → one
+ * `agent`-scope lesson "Default to terse, bulleted output." This is the engine
+ * that turns accumulated specifics into a small set of meaningful generalizations.
+ *
+ * Two layers, mirroring `consolidation-prep.ts`:
+ *   - The dispatcher (coverage-excluded, FS-heavy) enumerates the lesson files
+ *     on disk — the global `policies/agent-lessons.md` plus every per-agent
+ *     `policies/agents/<slug>/lessons.md` — and reads their contents.
+ *   - `buildRegeneralizationWorksheet(scopes, …)` — this pure markdown/XML
+ *     composer turns those contents into a `<feedback_regeneralization>` block.
+ *     Every output byte is a deterministic function of its inputs, so it stays
+ *     I/O-free and 100% coverable.
+ *
+ * Unlike the evening worksheet, this pass carries **no signals and no consume
+ * ids** — it neither promotes nor consumes; it only ranks the existing lessons
+ * (lowest-scored first, the same eviction order Step 4 already uses) and flags
+ * staleness / over-cap so the LLM's collapse honours the same caps. A scope is
+ * surfaced only when it holds at least {@link MIN_LESSONS_FOR_REGENERALIZATION}
+ * *active* lessons — you need two to collapse one — and the whole block is
+ * omitted when no scope qualifies, so a sparse vault adds nothing to the
+ * monthly prompt.
+ *
+ * **Promotion-neutral by construction.** Only *active* (non-provisional)
+ * lessons are surfaced for collapse. Provisional lessons are awaiting
+ * corroboration and are owned exclusively by the nightly evening pass — the
+ * single promotion authority (`promotion-gate.ts`). Offering them here would
+ * let the LLM merge two provisional lessons into one active lesson, summing
+ * their `ev` past the threshold and bypassing the gate's
+ * `ignored`-only-never-promotes guard (§3.5.1) — the exact sign-inversion the
+ * gate exists to kill. They stay in the file untouched; the task-flow tells the
+ * LLM to preserve any provisional lesson byte-for-byte.
+ */
+import { type CanonicalScope } from "./scope-parser.js";
+/** A scope needs at least this many *active* lessons before a collapse is possible. */
+export declare const MIN_LESSONS_FOR_REGENERALIZATION = 2;
+export interface RegeneralizationScopeInput {
+    /** `agent` (global) or `agent_slug` (per-agent) — the user scope is handled
+     *  by the existing nightly user-profile consolidation, not re-generalised. */
+    scope: CanonicalScope;
+    /** Canonical store path (`policies/agent-lessons.md` / `policies/agents/<slug>/lessons.md`). */
+    storeFile: string;
+    /** Current lessons-store file contents. */
+    existingFileMd: string;
+    /** Byte/entry caps for the scope (§6). */
+    caps: {
+        capBytes: number;
+        maxEntries: number;
+    };
+}
+export interface BuildRegeneralizationOptions {
+    nowIso: string;
+    recencyHalfLifeDays?: number;
+    /**
+     * Staleness horizon in days (`feedbackLessonStaleDays`, §4 step 7). A lesson
+     * whose `last=` predates `now − staleDays` and is not a `constraint` is
+     * flagged `stale="true"` so the LLM can drop it while collapsing. Omitted ⇒
+     * nothing is flagged stale.
+     */
+    staleDays?: number;
+}
+export interface RegeneralizationResult {
+    /** `<feedback_regeneralization>…</…>` block for verbatim injection. */
+    block: string;
+    /** Number of scopes surfaced (each with ≥ MIN_LESSONS_FOR_REGENERALIZATION active lessons). */
+    scopeCount: number;
+    /** Total *active* lessons surfaced across all scopes (provisional excluded). */
+    lessonCount: number;
+}
+/**
+ * Compose the `<feedback_regeneralization>` block. Returns `null` when no scope
+ * holds at least {@link MIN_LESSONS_FOR_REGENERALIZATION} *active*
+ * (non-provisional) lessons — there is nothing to collapse, so the caller
+ * stamps nothing (no empty block in the prompt). Provisional lessons are
+ * excluded from the collapse set (see module header) but still counted in each
+ * scope's `current_entries` / `over_cap` so the cap status stays whole-file
+ * truthful. Scopes are emitted in input order.
+ */
+export declare function buildRegeneralizationWorksheet(scopes: ReadonlyArray<RegeneralizationScopeInput>, opts: BuildRegeneralizationOptions): RegeneralizationResult | null;

package/dist/core/feedback/regeneralization-prep.js

@@ -0,0 +1,152 @@
+/**
+ * Feedback Learning Loop — monthly re-generalization pre-step
+ * (FEEDBACK_LEARNING_LOOP_DESIGN.md §4 "Monthly re-generalization", Phase 5).
+ *
+ * The deterministic, daemon-side half of the *monthly* collapse. Where the
+ * nightly evening-review pre-step (`consolidation-prep.ts`) folds unconsumed
+ * *signals* into lessons, the monthly pass re-reads the *already-consolidated*
+ * lesson stores and surfaces them so the LLM can collapse several specific
+ * lessons that share a theme into one higher-level principle — e.g. three
+ * "shorter mail summary" / "shorter standup" / "shorter report" lessons → one
+ * `agent`-scope lesson "Default to terse, bulleted output." This is the engine
+ * that turns accumulated specifics into a small set of meaningful generalizations.
+ *
+ * Two layers, mirroring `consolidation-prep.ts`:
+ *   - The dispatcher (coverage-excluded, FS-heavy) enumerates the lesson files
+ *     on disk — the global `policies/agent-lessons.md` plus every per-agent
+ *     `policies/agents/<slug>/lessons.md` — and reads their contents.
+ *   - `buildRegeneralizationWorksheet(scopes, …)` — this pure markdown/XML
+ *     composer turns those contents into a `<feedback_regeneralization>` block.
+ *     Every output byte is a deterministic function of its inputs, so it stays
+ *     I/O-free and 100% coverable.
+ *
+ * Unlike the evening worksheet, this pass carries **no signals and no consume
+ * ids** — it neither promotes nor consumes; it only ranks the existing lessons
+ * (lowest-scored first, the same eviction order Step 4 already uses) and flags
+ * staleness / over-cap so the LLM's collapse honours the same caps. A scope is
+ * surfaced only when it holds at least {@link MIN_LESSONS_FOR_REGENERALIZATION}
+ * *active* lessons — you need two to collapse one — and the whole block is
+ * omitted when no scope qualifies, so a sparse vault adds nothing to the
+ * monthly prompt.
+ *
+ * **Promotion-neutral by construction.** Only *active* (non-provisional)
+ * lessons are surfaced for collapse. Provisional lessons are awaiting
+ * corroboration and are owned exclusively by the nightly evening pass — the
+ * single promotion authority (`promotion-gate.ts`). Offering them here would
+ * let the LLM merge two provisional lessons into one active lesson, summing
+ * their `ev` past the threshold and bypassing the gate's
+ * `ignored`-only-never-promotes guard (§3.5.1) — the exact sign-inversion the
+ * gate exists to kill. They stay in the file untouched; the task-flow tells the
+ * LLM to preserve any provisional lesson byte-for-byte.
+ */
+import { extractMarkdownSection, parseLessonsSection, } from "./lesson-format.js";
+import { scoreLesson, isLessonStale, DEFAULT_RECENCY_HALFLIFE_DAYS, } from "./eviction-scorer.js";
+import { formatScope, scopeSectionSlug } from "./scope-parser.js";
+/** A scope needs at least this many *active* lessons before a collapse is possible. */
+export const MIN_LESSONS_FOR_REGENERALIZATION = 2;
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function round2(value) {
+    return (Math.round(value * 100) / 100).toFixed(2);
+}
+/** Collapse a one-line excerpt of a lesson for an XML text node.
+ *  The clip strips a trailing lone high surrogate so cutting through an
+ *  astral char (emoji) can't leave a U+FFFD in the worksheet. */
+function inline(text, max = 300) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const clipped = flat.length > max
+        ? `${flat.slice(0, max - 1).replace(/[\uD800-\uDBFF]$/, "")}…`
+        : flat;
+    return xmlEscape(clipped);
+}
+function renderScope(input, sectionBody, activeLessons, totalEntries, opts, out) {
+    const label = formatScope(input.scope);
+    const section = scopeSectionSlug(input.scope);
+    const halfLife = opts.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALFLIFE_DAYS;
+    // `current_bytes` / `current_entries` describe the on-disk `## Lessons`
+    // SECTION (active + provisional) — the §6 cap unit
+    // (`lessonsSectionByteLength` in lesson-format.ts), the same unit the
+    // nightly worksheet's `over_cap` and the eviction engine measure. The
+    // whole-file measure used previously disagreed with the nightly pass in a
+    // narrow band (frontmatter + `# heading` overhead), making the two
+    // worksheets contradict each other on the same store. `over_cap` covers
+    // the full entry set, not just the collapsible active subset — the LLM's
+    // Step-12 eviction targets the disk cap. The caller extracted
+    // `sectionBody` once during eligibility (a scope is only eligible when
+    // its `## Lessons` section parsed), so it is measured here verbatim.
+    const currentBytes = Buffer.byteLength(sectionBody, "utf-8");
+    const overCap = currentBytes > input.caps.capBytes || totalEntries > input.caps.maxEntries;
+    const provisionalHeld = totalEntries - activeLessons.length;
+    // Ascending score → rank 1 = lowest score = drop-first, the same convention
+    // the evening worksheet uses so the LLM reads both with one mental model.
+    const ranked = [...activeLessons].sort((a, b) => scoreLesson(a, opts.nowIso, undefined, halfLife) -
+        scoreLesson(b, opts.nowIso, undefined, halfLife));
+    out.push(`  <scope label="${xmlEscape(label)}" store="${xmlEscape(input.storeFile)}" ` +
+        `section="${xmlEscape(section)}" ` +
+        `cap_bytes="${input.caps.capBytes}" max_entries="${input.caps.maxEntries}" ` +
+        `current_bytes="${currentBytes}" current_entries="${totalEntries}" ` +
+        `provisional_held="${provisionalHeld}" over_cap="${overCap}">`);
+    out.push(`    <lessons note="active (non-provisional) lessons only, ranked by eviction ` +
+        `score (rank 1 = lowest, drop-first); cluster lessons that share a theme ` +
+        `and collapse each cluster into ONE higher-level principle; drop any lesson ` +
+        `marked stale=&quot;true&quot; unless it joins a cluster; never collapse ` +
+        `across a contradiction; preserve any provisional lesson in the file ` +
+        `byte-for-byte — they await corroboration and are not yours to collapse or promote">`);
+    ranked.forEach((lesson, idx) => {
+        out.push(`      <lesson rank="${idx + 1}" score="${round2(scoreLesson(lesson, opts.nowIso, undefined, halfLife))}" ev="${lesson.ev}" kind="${lesson.kind}" last="${lesson.last}" ` +
+            `provisional="${lesson.provisional}" ` +
+            `stale="${isLessonStale(lesson, opts.nowIso, opts.staleDays)}">` +
+            `${inline(lesson.text)}</lesson>`);
+    });
+    out.push("    </lessons>");
+    out.push("  </scope>");
+}
+/**
+ * Compose the `<feedback_regeneralization>` block. Returns `null` when no scope
+ * holds at least {@link MIN_LESSONS_FOR_REGENERALIZATION} *active*
+ * (non-provisional) lessons — there is nothing to collapse, so the caller
+ * stamps nothing (no empty block in the prompt). Provisional lessons are
+ * excluded from the collapse set (see module header) but still counted in each
+ * scope's `current_entries` / `over_cap` so the cap status stays whole-file
+ * truthful. Scopes are emitted in input order.
+ */
+export function buildRegeneralizationWorksheet(scopes, opts) {
+    const eligible = [];
+    for (const input of scopes) {
+        // Single extraction per scope — `renderScope` reuses this body for its
+        // `current_bytes` measure instead of re-extracting (the old double
+        // extraction left renderScope with an unreachable missing-section arm).
+        const sectionBody = extractMarkdownSection(input.existingFileMd, "Lessons");
+        if (!sectionBody)
+            continue;
+        const allLessons = parseLessonsSection(sectionBody);
+        // Collapse the ACTIVE set only — provisional lessons are owned by the
+        // evening promotion gate (see module header); merging them here would
+        // bypass the `ignored`-only-never-promotes guard.
+        const active = allLessons.filter((lesson) => !lesson.provisional);
+        if (active.length >= MIN_LESSONS_FOR_REGENERALIZATION) {
+            eligible.push({ input, sectionBody, active, totalEntries: allLessons.length });
+        }
+    }
+    if (eligible.length === 0)
+        return null;
+    const out = [];
+    out.push(`<feedback_regeneralization generated_at="${xmlEscape(opts.nowIso)}" ` +
+        `scopes="${eligible.length}">`);
+    let lessonCount = 0;
+    for (const { input, sectionBody, active, totalEntries } of eligible) {
+        renderScope(input, sectionBody, active, totalEntries, opts, out);
+        lessonCount += active.length;
+    }
+    out.push("</feedback_regeneralization>");
+    return {
+        block: out.join("\n"),
+        scopeCount: eligible.length,
+        lessonCount,
+    };
+}