@aitne/daemon 0.1.9 → 0.1.10

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,139 @@
+/**
+ * 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. */
+function inline(text, max = 300) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const clipped = flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+    return xmlEscape(clipped);
+}
+function parseScopeLessons(existingFileMd) {
+    const sectionBody = extractMarkdownSection(existingFileMd, "Lessons");
+    return sectionBody ? parseLessonsSection(sectionBody) : [];
+}
+function renderScope(input, activeLessons, totalEntries, opts, out) {
+    const label = formatScope(input.scope);
+    const section = scopeSectionSlug(input.scope);
+    const halfLife = opts.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALFLIFE_DAYS;
+    const currentBytes = Buffer.byteLength(input.existingFileMd, "utf-8");
+    // `current_bytes` / `current_entries` describe the WHOLE on-disk file
+    // (active + provisional), because that is exactly what the byte/entry caps
+    // guard (§6). `over_cap` therefore reflects the real file state, not the
+    // collapsible subset — the LLM's Step-12 eviction targets the disk cap.
+    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) {
+        const allLessons = parseScopeLessons(input.existingFileMd);
+        // 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, 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, active, totalEntries } of eligible) {
+        renderScope(input, active, totalEntries, opts, out);
+        lessonCount += active.length;
+    }
+    out.push("</feedback_regeneralization>");
+    return {
+        block: out.join("\n"),
+        scopeCount: eligible.length,
+        lessonCount,
+    };
+}

package/dist/core/feedback/scope-parser.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Feedback Learning Loop — scope grammar (FEEDBACK_LEARNING_LOOP_DESIGN.md §3.3).
+ *
+ * A feedback signal / lesson carries a **scope** that decides *who sees it*.
+ * This module is the single source of truth that maps the DB row's
+ * `(scope_type, scope_ref)` pair onto:
+ *   - a canonical, human-readable scope string (`user`, `agent`,
+ *     `agent:report-writer`, `channel:slack`, …) used in worksheet XML and
+ *     lesson-file headers, and
+ *   - the writable vault file that stores that scope's lessons.
+ *
+ * Pure logic, no I/O — the §4 division-of-labour "scope parser" covered module.
+ * Phase 2 only *stores* `user` + `agent`; the parser still recognises the full
+ * v2 grammar (`agent_slug`, `channel`, `task`, `integration`) so forward-compat
+ * rows round-trip rather than throwing, but `scopeStoreFile` returns `null` for
+ * the not-yet-stored classes — the caller treats that as "surface but do not
+ * persist a lesson file yet".
+ */
+import type { FeedbackScopeType } from "../../db/feedback-signals-store.js";
+/** Parsed, normalised scope. `agent_slug` collapses to `kind: "agent_slug"`. */
+export type CanonicalScope = {
+    kind: "user";
+} | {
+    kind: "agent";
+} | {
+    kind: "agent_slug";
+    ref: string;
+} | {
+    kind: "channel";
+    ref: string;
+} | {
+    kind: "task";
+    ref: string;
+} | {
+    kind: "integration";
+    ref: string;
+};
+/**
+ * Parse a `(scope_type, scope_ref)` pair into a {@link CanonicalScope}.
+ * Returns `null` when the type is unknown or a ref-required class is missing
+ * its ref — the caller drops such rows from the worksheet rather than guessing.
+ */
+export declare function parseScope(scopeType: string, scopeRef: string | null | undefined): CanonicalScope | null;
+/**
+ * Canonical human-readable scope label used in worksheet XML attributes and
+ * the `<!-- scope: … -->` lesson-file header. `agent:<slug>` is the literal
+ * answer to requirement #3 ("feedback on a generated agent's output").
+ */
+export declare function formatScope(scope: CanonicalScope): string;
+/**
+ * Stable grouping key for a scope — used by the consolidation pre-step to
+ * bucket unconsumed signals by `(scope_type, scope_ref)` (§4 step 1). Equal
+ * for two signals that target the same lesson destination.
+ */
+export declare function scopeKey(scope: CanonicalScope): string;
+/**
+ * Resolve the writable-vault relative path that stores a scope's lessons.
+ *   - `user`       → `identity/profile.md` (`## Learned Context` section)
+ *   - `agent`      → `policies/agent-lessons.md`
+ *   - `agent:slug` → `policies/agents/<slug>/lessons.md`
+ *   - everything else (v2 channel/task/integration) → `null` (not yet stored)
+ *
+ * The `agent:<slug>` ref is path-validated with {@link isSafeAgentSlug} before
+ * it is composed into a vault path — the same guard the inject side applies to
+ * `event.data.agentId` (`context-builder.ts`), so both consumers of a slug
+ * reject the same unsafe shapes (`agentLessonsPath` itself trusts a
+ * pre-validated slug). A path-unsafe ref yields `null` ("surface but do not
+ * persist"), so the consolidation worksheet never emits an unsafe `store=` for
+ * the LLM to PATCH. In practice the `/api/feedback` route + the behavioral
+ * sink only ever write a real `agents.id` ref, so this is pure defence-in-depth
+ * against a malformed / forged row.
+ */
+export declare function scopeStoreFile(scope: CanonicalScope): string | null;
+export declare function isSafeAgentSlug(value: string): boolean;
+/**
+ * The markdown section a scope's lessons live under, for PATCH `section=`
+ * targeting. `user` folds into the existing `## Learned Context`; lesson
+ * stores use `## Lessons`.
+ */
+export declare function scopeSectionSlug(scope: CanonicalScope): string;
+/**
+ * True when a scope type needs a ref to be valid. Exposed for the route /
+ * worksheet validators that mirror the §3.5.2 "scope_ref present iff
+ * scope_type=agent_slug" rule across the extended grammar.
+ */
+export declare function scopeNeedsRef(scopeType: FeedbackScopeType): boolean;

package/dist/core/feedback/scope-parser.js

@@ -0,0 +1,141 @@
+/**
+ * Feedback Learning Loop — scope grammar (FEEDBACK_LEARNING_LOOP_DESIGN.md §3.3).
+ *
+ * A feedback signal / lesson carries a **scope** that decides *who sees it*.
+ * This module is the single source of truth that maps the DB row's
+ * `(scope_type, scope_ref)` pair onto:
+ *   - a canonical, human-readable scope string (`user`, `agent`,
+ *     `agent:report-writer`, `channel:slack`, …) used in worksheet XML and
+ *     lesson-file headers, and
+ *   - the writable vault file that stores that scope's lessons.
+ *
+ * Pure logic, no I/O — the §4 division-of-labour "scope parser" covered module.
+ * Phase 2 only *stores* `user` + `agent`; the parser still recognises the full
+ * v2 grammar (`agent_slug`, `channel`, `task`, `integration`) so forward-compat
+ * rows round-trip rather than throwing, but `scopeStoreFile` returns `null` for
+ * the not-yet-stored classes — the caller treats that as "surface but do not
+ * persist a lesson file yet".
+ */
+import { agentLessonsPath, CONTEXT_RELATIVE_PATHS } from "../context-paths.js";
+/** Scope classes that require a `scope_ref` to be meaningful. */
+const REF_REQUIRED = new Set([
+    "agent_slug",
+    "channel",
+    "task",
+    "integration",
+]);
+/**
+ * Parse a `(scope_type, scope_ref)` pair into a {@link CanonicalScope}.
+ * Returns `null` when the type is unknown or a ref-required class is missing
+ * its ref — the caller drops such rows from the worksheet rather than guessing.
+ */
+export function parseScope(scopeType, scopeRef) {
+    const ref = typeof scopeRef === "string" ? scopeRef.trim() : "";
+    switch (scopeType) {
+        case "user":
+            return { kind: "user" };
+        case "agent":
+            return { kind: "agent" };
+        case "agent_slug":
+            return ref.length > 0 ? { kind: "agent_slug", ref } : null;
+        case "channel":
+            return ref.length > 0 ? { kind: "channel", ref } : null;
+        case "task":
+            return ref.length > 0 ? { kind: "task", ref } : null;
+        case "integration":
+            return ref.length > 0 ? { kind: "integration", ref } : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Canonical human-readable scope label used in worksheet XML attributes and
+ * the `<!-- scope: … -->` lesson-file header. `agent:<slug>` is the literal
+ * answer to requirement #3 ("feedback on a generated agent's output").
+ */
+export function formatScope(scope) {
+    switch (scope.kind) {
+        case "user":
+            return "user";
+        case "agent":
+            return "agent";
+        case "agent_slug":
+            return `agent:${scope.ref}`;
+        case "channel":
+            return `channel:${scope.ref}`;
+        case "task":
+            return `task:${scope.ref}`;
+        case "integration":
+            return `integration:${scope.ref}`;
+    }
+}
+/**
+ * Stable grouping key for a scope — used by the consolidation pre-step to
+ * bucket unconsumed signals by `(scope_type, scope_ref)` (§4 step 1). Equal
+ * for two signals that target the same lesson destination.
+ */
+export function scopeKey(scope) {
+    return formatScope(scope);
+}
+/**
+ * Resolve the writable-vault relative path that stores a scope's lessons.
+ *   - `user`       → `identity/profile.md` (`## Learned Context` section)
+ *   - `agent`      → `policies/agent-lessons.md`
+ *   - `agent:slug` → `policies/agents/<slug>/lessons.md`
+ *   - everything else (v2 channel/task/integration) → `null` (not yet stored)
+ *
+ * The `agent:<slug>` ref is path-validated with {@link isSafeAgentSlug} before
+ * it is composed into a vault path — the same guard the inject side applies to
+ * `event.data.agentId` (`context-builder.ts`), so both consumers of a slug
+ * reject the same unsafe shapes (`agentLessonsPath` itself trusts a
+ * pre-validated slug). A path-unsafe ref yields `null` ("surface but do not
+ * persist"), so the consolidation worksheet never emits an unsafe `store=` for
+ * the LLM to PATCH. In practice the `/api/feedback` route + the behavioral
+ * sink only ever write a real `agents.id` ref, so this is pure defence-in-depth
+ * against a malformed / forged row.
+ */
+export function scopeStoreFile(scope) {
+    switch (scope.kind) {
+        case "user":
+            return CONTEXT_RELATIVE_PATHS.user.profile;
+        case "agent":
+            return CONTEXT_RELATIVE_PATHS.agentLessons;
+        case "agent_slug":
+            return isSafeAgentSlug(scope.ref) ? agentLessonsPath(scope.ref) : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Path-safety guard for an `agent:<slug>` ref before it is interpolated into a
+ * vault file path (`agentLessonsPath`). The Phase-4 inject path reads
+ * `event.data.agentId` — a `Record<string, unknown>` value set by the dispatch
+ * site from `resolveAgentId()` — and joins it under `policies/agents/`. Although
+ * `resolveAgentId` only ever returns DB-verified / built-in-registry slugs,
+ * defence-in-depth requires the consuming side validate the shape rather than
+ * trust the carrier: the slug must be a single safe segment (kebab-case-ish,
+ * the same `[a-z0-9._-]` alphabet `deriveSlug` and the context-write whitelist
+ * use), start alphanumeric (so `.`/`..` are rejected outright), and contain no
+ * `..` traversal or `/` separator. A failing value yields no self block rather
+ * than a path escape.
+ */
+const SAFE_AGENT_SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/;
+export function isSafeAgentSlug(value) {
+    return SAFE_AGENT_SLUG_RE.test(value) && !value.includes("..");
+}
+/**
+ * The markdown section a scope's lessons live under, for PATCH `section=`
+ * targeting. `user` folds into the existing `## Learned Context`; lesson
+ * stores use `## Lessons`.
+ */
+export function scopeSectionSlug(scope) {
+    return scope.kind === "user" ? "learned_context" : "lessons";
+}
+/**
+ * True when a scope type needs a ref to be valid. Exposed for the route /
+ * worksheet validators that mirror the §3.5.2 "scope_ref present iff
+ * scope_type=agent_slug" rule across the extended grammar.
+ */
+export function scopeNeedsRef(scopeType) {
+    return REF_REQUIRED.has(scopeType);
+}