@wrongstack/core 0.302.2 → 0.305.0

package/dist/coordination/agents/project-agent-auto-optimize.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Automatic learning optimization.
+ *
+ * Capture is automatic, but distillation used to be a button someone had to
+ * press — so a role kept accumulating raw directives and its skills never grew
+ * unless a human remembered to run `/agent-improve <role> optimize`. This
+ * scheduler closes that gap: it watches captures, decides when a role has
+ * earned a pass, and runs `optimizeProjectAgentLearning` in the background.
+ *
+ * Design constraints, in priority order:
+ *
+ * 1. **Never block user-facing work.** Every pass is detached and debounced;
+ *    a capture returns immediately.
+ * 2. **Never stampede.** One pass at a time process-wide, one pending pass per
+ *    role, and a per-role cooldown so a chatty fleet cannot spend the budget
+ *    on back-to-back optimizations of the same buffer.
+ * 3. **Never crash the host.** Failures are swallowed into an exponential
+ *    backoff; a dead provider degrades to "no optimization" and not to a hot
+ *    retry loop or a rejected promise nobody awaits.
+ * 4. **Do something useful without a model.** With no LLM available the pass
+ *    still writes the deterministic per-skill addenda, so tagged learning
+ *    reaches the skill layer on a headless box.
+ */
+import { type LearningOptimizerLlm, type OptimizeLearningResult } from './project-agent-optimizer.js';
+export interface AutoOptimizePolicy {
+    /** Master switch. Default true. */
+    enabled: boolean;
+    /** Raw buffer size that makes a role eligible. Default = the soft limit. */
+    thresholdBytes: number;
+    /** Never optimize a nearly-empty buffer, whatever its byte size. */
+    minEntries: number;
+    /**
+     * Directives already routed to a skill that has no addendum yet. Reaching
+     * this count makes a role eligible even below `thresholdBytes` — getting
+     * learning into the skill layer promptly is the point of the loop, and
+     * waiting for the buffer to fatten delays it for no reason.
+     */
+    minPendingSkillDirectives: number;
+    /** Minimum gap between two automatic passes for one role. */
+    minIntervalMs: number;
+    /** Quiet period after the last capture before a pass may start. */
+    debounceMs: number;
+}
+export declare const DEFAULT_AUTO_OPTIMIZE_POLICY: AutoOptimizePolicy;
+/** Shape accepted from config, where every field is independently optional. */
+export type AutoOptimizePolicyOverrides = {
+    [K in keyof AutoOptimizePolicy]?: AutoOptimizePolicy[K] | undefined;
+} & {
+    sweepOnStart?: boolean | undefined;
+};
+export declare function resolveAutoOptimizePolicy(overrides?: AutoOptimizePolicyOverrides | undefined): AutoOptimizePolicy;
+export type AutoOptimizeSkipReason = 'disabled' | 'learning-paused' | 'too-few-entries' | 'below-threshold' | 'cooling-down';
+export type AutoOptimizeDecision = {
+    eligible: true;
+    reason: 'size' | 'pending-skills';
+} | {
+    eligible: false;
+    reason: AutoOptimizeSkipReason;
+};
+/**
+ * Pure eligibility check — no timers, no I/O beyond reading the role's files.
+ * Exported so the decision can be tested and surfaced in a status view
+ * without running a pass.
+ */
+export declare function evaluateAutoOptimize(role: string, projectRoot: string | undefined, policy: AutoOptimizePolicy, now?: number): AutoOptimizeDecision;
+export interface AutoOptimizeEvent {
+    role: string;
+    trigger: 'size' | 'pending-skills' | 'manual-sweep';
+    result?: OptimizeLearningResult | undefined;
+    error?: string | undefined;
+}
+export interface LearningOptimizationSchedulerOptions {
+    projectRoot: string;
+    getPolicy: () => AutoOptimizePolicy;
+    /** Resolved lazily so a pass never holds a provider open between runs. */
+    getLlm: () => Promise<LearningOptimizerLlm | undefined> | LearningOptimizerLlm | undefined;
+    onEvent?: ((event: AutoOptimizeEvent) => void) | undefined;
+    /** Injectable clock/timer for deterministic tests. */
+    now?: (() => number) | undefined;
+    scheduleTimer?: ((fn: () => void, ms: number) => NodeJS.Timeout) | undefined;
+    cancelTimer?: ((handle: NodeJS.Timeout) => void) | undefined;
+}
+export declare class LearningOptimizationScheduler {
+    private readonly opts;
+    private readonly pending;
+    private readonly failures;
+    private running;
+    private inFlight;
+    private disposed;
+    constructor(opts: LearningOptimizationSchedulerOptions);
+    private get now();
+    private schedule;
+    /**
+     * Called after a capture persisted new directives. Debounced per role: a
+     * burst of captures collapses into one pass.
+     */
+    notifyCaptured(role: string): void;
+    /**
+     * Evaluate every role that has learning data and queue the eligible ones.
+     * Run once at host start so roles that crossed the threshold before the
+     * scheduler existed are not stuck waiting for their next capture.
+     */
+    sweep(roles: readonly string[]): void;
+    private runIfEligible;
+    /** Serialize passes: one optimization at a time, process-wide. */
+    private enqueue;
+    private execute;
+    private recordFailure;
+    /** Role currently being optimized, for status surfaces. */
+    activeRole(): string | null;
+    /** Cancel pending debounces. Safe to call more than once. */
+    dispose(): void;
+    /** Await the queue — tests only; production never blocks on a pass. */
+    idle(): Promise<void>;
+}
+//# sourceMappingURL=project-agent-auto-optimize.d.ts.map

package/dist/coordination/agents/project-agent-capture-window.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capture rate-limiting window.
+ *
+ * The frequency cap is documented as "per session", but the counters used to
+ * live in module-level Maps that were never reset. In a long-lived project
+ * daemon that made the cap "3 captures per role per *process lifetime*" — the
+ * observable symptom being roles that silently stopped learning days ago.
+ *
+ * The window is now time-boxed: counters roll over after
+ * `CAPTURE_SESSION_WINDOW_MS`, and a host can reset them explicitly when a real
+ * session boundary occurs (`/clear`, resume, new REPL turn batch).
+ */
+/** Minimum spacing between two automatic captures for one role. */
+export declare const CAPTURE_COOLDOWN_MS = 120000;
+/** Automatic captures allowed per role within one window. */
+export declare const CAPTURE_MAX_PER_SESSION = 3;
+/** How long a counting window lasts before it rolls over. */
+export declare const CAPTURE_SESSION_WINDOW_MS: number;
+export declare function captureWindowState(key: string, now?: number): {
+    count: number;
+    lastCaptureAt: number | undefined;
+    remaining: number;
+};
+export declare function recordCaptureAttempt(key: string, now?: number): void;
+/** Drop every counter. Called on an explicit session boundary and by tests. */
+export declare function resetCaptureWindows(): void;
+/** Drop the counters for one role/project key. */
+export declare function resetCaptureWindow(key: string): void;
+//# sourceMappingURL=project-agent-capture-window.d.ts.map

package/dist/coordination/agents/project-agent-config-io.d.ts

@@ -0,0 +1,11 @@
+import type { ProjectAgentConfig } from './project-agent-identity-types.js';
+/**
+ * Load the project-level agent config for a given role.
+ * Returns `undefined` when no project override exists.
+ *
+ * Lives in its own module (rather than in `project-agent-identity.ts`) so the
+ * skill layer can read the role's `skillNames` override without importing the
+ * identity module, which imports the skill layer.
+ */
+export declare function loadProjectAgentConfig(role: string, projectRoot?: string): ProjectAgentConfig | undefined;
+//# sourceMappingURL=project-agent-config-io.d.ts.map

package/dist/coordination/agents/project-agent-consolidation.d.ts

@@ -1,7 +1,15 @@
+import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
 export interface ConsolidationMetadata {
     /** ISO timestamp of the last consolidation. */
     consolidatedAt: string;
-    /** Number of raw learned.md entries that were synthesized. */
+    /**
+     * Number of raw `learned.md` **directives** that were synthesized.
+     *
+     * Counted with the structured parser. It used to be counted with
+     * `splitLearnedEntries`, which returns 2 for any structured buffer, so the
+     * freshness comparison in `buildProjectContextualizedPrompt` compared 2
+     * against 2 forever and the delta-injection branch was unreachable.
+     */
     sourceEntryCount: number;
     /** Byte size of the raw learned.md at consolidation time. */
     sourceBytes: number;
@@ -11,11 +19,35 @@ export interface ConsolidationMetadata {
     trigger: 'manual' | 'automatic';
     /** Optional model that produced the consolidation. */
     model?: string | undefined;
+    /** Whether the raw buffer was archived and reset after synthesis. */
+    pruned?: boolean | undefined;
+    /** Archive file holding the pre-prune raw buffer, when pruned. */
+    archivePath?: string | undefined;
+    /** Skill addenda refreshed by this pass. */
+    skills?: string[] | undefined;
 }
+/** Structured directives in the raw buffer, with legacy-format fallback. */
+export declare function readRawLearnedEntries(role: string, projectRoot?: string): StructuredLearnedEntry[];
+/**
+ * The role document's path, for callers that need to rewrite it in place
+ * without going through the full save-and-record-metadata pass.
+ */
+export declare function consolidatedDocumentPath(role: string, projectRoot?: string): string;
 export declare function loadProjectAgentConsolidated(role: string, projectRoot?: string): string;
 export declare function loadConsolidationMetadata(role: string, projectRoot?: string): ConsolidationMetadata | undefined;
 export declare function isConsolidated(role: string, projectRoot?: string): boolean;
-export declare function saveProjectAgentConsolidated(role: string, content: string, projectRoot?: string, metadata?: Partial<ConsolidationMetadata>): string;
+export interface SaveConsolidationOptions extends Partial<ConsolidationMetadata> {
+    /**
+     * Archive the raw buffer and reset it to an empty structured document.
+     *
+     * Consolidation used to leave `learned.md` untouched, so a role whose buffer
+     * had crossed the soft limit stayed over it forever and never captured
+     * again. Pruning is what actually closes the optimize→learn loop; the
+     * pre-prune buffer is kept under `archive/` for audit.
+     */
+    prune?: boolean | undefined;
+}
+export declare function saveProjectAgentConsolidated(role: string, content: string, projectRoot?: string, options?: SaveConsolidationOptions): string;
 export declare function clearProjectAgentConsolidated(role: string, projectRoot?: string): void;
 export declare function buildConsolidationInstruction(role: string, projectRoot?: string): {
     instruction: string;

package/dist/coordination/agents/project-agent-directive-outcome.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Outcome attribution for captured directives.
+ *
+ * Capture answers "what did the agent conclude?". This module answers the
+ * question the loop was missing: **did that conclusion help?** Without it the
+ * environment's reward reached `affinity.json` and stopped there, so a directive
+ * that made every task worse was injected forever and could only ever leave the
+ * buffer by growing old.
+ *
+ * The attribution is deliberately cheap and model-free. When a task finishes,
+ * its final report is scanned for evidence that each already-stored directive
+ * was actually exercised — its anchors (commands, paths, package names, which
+ * capture already extracts into `entry.how`) appearing verbatim, or enough of
+ * its distinctive wording to be unambiguous. Every directive that was exercised
+ * takes the task's outcome onto its own record.
+ *
+ * This is correlation, not proof: a directive can be mentioned and irrelevant,
+ * or decisive and unmentioned. It is used accordingly — to order eviction, to
+ * protect proven rules from being overwritten, to retire rules that keep losing,
+ * and to tell the distillation pass which directives earned their place. None of
+ * those decisions is safe to make on age alone, which is what they used before.
+ */
+import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
+/** Trials a directive must have before a bad record can retire it. */
+export declare const DIRECTIVE_QUARANTINE_MIN_APPLIED = 8;
+/** Utility below which a directive with enough trials is retired. */
+export declare const DIRECTIVE_QUARANTINE_MAX_UTILITY = 0.3;
+/**
+ * Whether `report` shows this directive was exercised.
+ *
+ * One anchor is enough: anchors are exact commands, paths and package names, so
+ * their appearance in a report is a direct statement that the thing the
+ * directive is about was touched. Directives with no anchors fall back to
+ * wording, which needs a high bar because generic prose overlaps easily.
+ */
+export declare function directiveWasApplied(entry: StructuredLearnedEntry, report: string): boolean;
+export interface DirectiveOutcomeResult {
+    role: string;
+    /** Directives credited with this task's outcome. */
+    attributed: number;
+    /** Directives retired into `quarantine.md` by this update. */
+    quarantined: string[];
+}
+/**
+ * Fold one completed task's outcome into the record of every directive it
+ * exercised, then retire the ones whose record has become bad enough.
+ *
+ * Must run **before** the same output is captured: a directive written by this
+ * task has not been tested by this task, and crediting it here would let every
+ * new directive vouch for itself.
+ *
+ * Can throw on an invalid role or an unwritable role directory. Callers on the
+ * task-completion path must swallow it: a lost outcome costs ranking quality,
+ * which is never worth failing a completed task over.
+ */
+export declare function recordDirectiveOutcomes(role: string, report: string, succeeded: boolean, projectRoot?: string): DirectiveOutcomeResult;
+//# sourceMappingURL=project-agent-directive-outcome.d.ts.map

package/dist/coordination/agents/project-agent-files.d.ts

@@ -1,8 +1,17 @@
 import type { ProjectAgentConfig, RoleKnowledgeManifest } from './project-agent-identity-types.js';
 /**
- * Write or update the learned wisdom file for a given role.
- * Appends to existing content when `mode` is 'append'; replaces when
- * it is 'replace'. Returns the full path written so callers can log it.
+ * Write or update the learned instruction buffer for a given role.
+ *
+ * `append` (the "teach this agent" flow) merges the text into the **structured**
+ * entry list rather than concatenating it after the rendered document. Raw
+ * concatenation used to be silently destructive: the structured parser only
+ * falls back to the legacy chunk path when it finds no stamped entries, so a
+ * taught paragraph appended to a stamped buffer was invisible to the parser and
+ * the next capture — which re-renders the whole file from parsed entries —
+ * deleted it without a trace.
+ *
+ * `replace` writes the content verbatim (the review/edit surfaces own the
+ * document at that point).
  */
 export declare function updateProjectAgentLearned(role: string, content: string, projectRoot?: string, mode?: 'append' | 'replace'): string;
 /**

package/dist/coordination/agents/project-agent-identity-types.d.ts

@@ -70,6 +70,10 @@ export interface LearnedCaptureResult {
     skipped: number;
     status: 'captured' | 'disabled' | 'empty_output' | 'no_blocks' | 'guarded' | 'quality_rejected';
     reason?: string | undefined;
+    /** Skills the captured directives were routed to, if any. */
+    skills?: string[] | undefined;
+    /** Older directives evicted to keep the buffer inside its budget. */
+    evicted?: number | undefined;
 }
 /**
  * Current-knowledge manifest for a role: what live facts the agent should

package/dist/coordination/agents/project-agent-identity.d.ts

@@ -19,17 +19,27 @@
  */
 import { existsSync } from 'node:fs';
 import type { SubagentConfig } from '../../types/multi-agent.js';
+import { CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION } from './project-agent-capture-window.js';
 import { type ConsolidationMetadata } from './project-agent-consolidation.js';
 import type { LearnedCaptureResult, ProjectAgentConfig, RoleKnowledgeManifest } from './project-agent-identity-types.js';
 import { type ProjectAgentLearningPolicy } from './project-agent-learning-policy.js';
 import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
+export { type AutoOptimizeDecision, type AutoOptimizeEvent, type AutoOptimizePolicy, type AutoOptimizePolicyOverrides, DEFAULT_AUTO_OPTIMIZE_POLICY, evaluateAutoOptimize, LearningOptimizationScheduler, type LearningOptimizationSchedulerOptions, resolveAutoOptimizePolicy, } from './project-agent-auto-optimize.js';
+export { CAPTURE_SESSION_WINDOW_MS, resetCaptureWindow, resetCaptureWindows, } from './project-agent-capture-window.js';
+export { loadProjectAgentConfig } from './project-agent-config-io.js';
 export { validateProjectAgentConfig } from './project-agent-config-validation.js';
-export { buildConsolidationInstruction, type ConsolidationMetadata, clearProjectAgentConsolidated, isConsolidated, loadConsolidationMetadata, loadProjectAgentConsolidated, saveProjectAgentConsolidated, } from './project-agent-consolidation.js';
+export { buildConsolidationInstruction, type ConsolidationMetadata, clearProjectAgentConsolidated, consolidatedDocumentPath, isConsolidated, loadConsolidationMetadata, loadProjectAgentConsolidated, readRawLearnedEntries, type SaveConsolidationOptions, saveProjectAgentConsolidated, } from './project-agent-consolidation.js';
+export { DIRECTIVE_QUARANTINE_MAX_UTILITY, DIRECTIVE_QUARANTINE_MIN_APPLIED, type DirectiveOutcomeResult, directiveWasApplied, recordDirectiveOutcomes, } from './project-agent-directive-outcome.js';
 export type { CreateProjectAgentInput, LearnedCaptureResult, ProjectAgentConfig, ProjectAgentProfile, RoleKnowledgeManifest, } from './project-agent-identity-types.js';
+export { splitLearnedEntries, tokenOverlap } from './project-agent-learning-entries.js';
 export { classifyLearnedEntry, LEARNED_ENTRY_MAX_CHARS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedEntryCategory, normalizeLearnedEntry, } from './project-agent-learning-normalize.js';
-export { loadProjectAgentLearningPolicy, type ProjectAgentLearningPolicy, updateProjectAgentLearningPolicy, } from './project-agent-learning-policy.js';
-export { decomposeLearnedEntry, mergeStructuredEntries, parseLearnedEntryStamp, renderLearnedInstructions, type StructuredLearnedEntry, } from './project-agent-learning-structured.js';
+export { loadProjectAgentLearningPolicy, type ProjectAgentLearningPolicy, recordProjectAgentOptimizePass, updateProjectAgentLearningPolicy, } from './project-agent-learning-policy.js';
+export { DIRECTIVE_PROVEN_MIN_APPLIED, DIRECTIVE_PROVEN_MIN_UTILITY, decomposeLearnedEntry, directiveTrials, directiveUtility, enforceLearnedBudget, isProvenDirective, mergeStructuredEntries, parseLearnedEntryStamp, parseStructuredLearnedEntriesFromContent, renderLearnedInstructions, type StructuredLearnedEntry, } from './project-agent-learning-structured.js';
+export { type LearningOptimizerLlm, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, unwrapWholeDocumentFence, } from './project-agent-optimizer.js';
 export { assertProjectAgentRole } from './project-agent-paths.js';
+export { type QuarantinedDirective, quarantinePath, readQuarantinedDirectives, retiredDirectivesToWarnAbout, scrubRetiredLines, } from './project-agent-quarantine.js';
+export { buildSkillDistillInstruction, clearProjectSkillAugmentation, DEFAULT_EAGER_SKILL_LIMIT, listProjectSkillAugmentations, loadProjectSkillAugmentation, loadSkillAffinity, rankRoleSkills, recordSkillLoad, recordSkillOutcome, renderSkillAugmentation, resolveRoleSkillCandidates, routeDirectiveToSkill, SKILL_AUGMENTATION_MAX_BYTES, SKILL_EVIDENCE_HALF_LIFE_DAYS, type SkillAffinity, type SkillAffinityEntry, saveProjectSkillAugmentation, scoreSkillAffinity, setSkillPinned, } from './project-agent-skill-layer.js';
+export { CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION };
 export { listProjectAgentRoles, refreshProjectAgentIdentity, resetProjectAgentIdentity, updateProjectAgentConfig, updateProjectAgentIdentity, updateProjectAgentKnowledge, updateProjectAgentLearned, } from './project-agent-files.js';
 export { createProjectAgent, loadProjectAgentProfile, slugifyProjectAgentRole, } from './project-agent-profile.js';
 /**
@@ -39,11 +49,6 @@ export { createProjectAgent, loadProjectAgentProfile, slugifyProjectAgentRole, }
  * roles may opt into a deliberately narrow runtime.
  */
 export declare function createProjectAgentRoster(baseRoster: Record<string, SubagentConfig>, projectRoot?: string): Record<string, SubagentConfig>;
-/**
- * Load the project-level agent config for a given role.
- * Returns `undefined` when no project override exists.
- */
-export declare function loadProjectAgentConfig(role: string, projectRoot?: string): ProjectAgentConfig | undefined;
 /**
  * Load the project-level identity appendix for a given role.
  * Appended to the subagent prompt after the base role prompt and policy.
@@ -84,13 +89,17 @@ export declare function applyProjectAgentConfig(base: SubagentConfig, projectCon
 export declare function buildProjectContextualizedPrompt(basePrompt: string, role: string, projectRoot?: string, options?: {
     identityOverride?: string | undefined;
 }): string;
-export declare const CAPTURE_COOLDOWN_MS = 120000;
-export declare const CAPTURE_MAX_PER_SESSION = 3;
 /**
  * Check whether a new capture is allowed for this role. Returns a rejection
  * reason string when blocked, or undefined when capture may proceed.
+ *
+ * `existingSize` is accepted for call-site compatibility but no longer gates
+ * anything: an over-budget buffer is now trimmed at write time
+ * (`enforceLearnedBudget`) instead of blocking every future capture. The old
+ * size gate had no self-clearing path, so the roles with the most learning
+ * were the ones that had silently stopped learning.
  */
-export declare function canCaptureNewLearned(role: string, existingSize: number, isManual: boolean, projectRoot?: string): string | undefined;
+export declare function canCaptureNewLearned(role: string, _existingSize: number, isManual: boolean, projectRoot?: string): string | undefined;
 /**
  * Per-role learning stats for monitoring UIs.
  */
@@ -116,6 +125,24 @@ export interface ProjectAgentLearnStats {
     isConsolidated: boolean;
     /** Consolidation metadata, if a consolidation has been performed. */
     consolidation?: ConsolidationMetadata | undefined;
+    /** Skills this project has developed a dedicated addendum for. */
+    skills: string[];
+    /** Directives already routed to a skill and awaiting distillation. */
+    skilledEntryCount: number;
+    /**
+     * How the buffer is actually performing, not just how big it is.
+     *
+     * `lifetimeCaptureCount` measures volume, which says nothing about whether
+     * the role is learning the right things. These three do:
+     * `provenEntryCount` is directives with a real track record, `deadEntryCount`
+     * is directives that have never been exercised at all (a high share means the
+     * agent is writing things nobody uses), and `directiveHitRate` is the share
+     * of applications that ended in a successful task.
+     */
+    appliedEntryCount: number;
+    deadEntryCount: number;
+    /** `null` until at least one directive has been exercised. */
+    directiveHitRate: number | null;
 }
 export declare function getProjectAgentLearnStats(role: string, projectRoot?: string): ProjectAgentLearnStats;
 /**

package/dist/coordination/agents/project-agent-learning-entries.d.ts

@@ -3,8 +3,14 @@
  */
 export declare function tokenOverlap(a: string, b: string): number;
 /**
- * Split an existing learned.md body into individual entries.
- * Entries are delimited by `---\n\n` sequences.
+ * Split a **legacy** learned.md body into individual entries.
+ *
+ * Entries are delimited by `---` runs, which is only meaningful for the old
+ * append-only journal format. The structured document uses `---` exactly once
+ * (before its footer), so this function returns 2 chunks for any structured
+ * buffer regardless of how many directives it holds. Callers that need a real
+ * entry count must use `parseStructuredLearnedEntries` — this one exists only
+ * to migrate pre-structured files.
  */
 export declare function splitLearnedEntries(body: string): string[];
 //# sourceMappingURL=project-agent-learning-entries.d.ts.map

package/dist/coordination/agents/project-agent-learning-policy.d.ts

@@ -5,7 +5,28 @@ export interface ProjectAgentLearningPolicy {
     lifetimeCaptureCount: number;
     lastCaptureAt?: string | undefined;
     lastCaptureSource?: 'automatic' | 'manual' | 'taught' | undefined;
+    /**
+     * When an optimization pass last ran to completion for this role, whatever it
+     * managed to do.
+     *
+     * The auto-optimize cooldown used to read `consolidation.json` alone, which is
+     * only written when a model produced a role document. A pass that ran without
+     * a model still rewrote every skill addendum and still left no trace, so on a
+     * headless box `minIntervalMs` never applied and a full pass re-ran after
+     * every capture.
+     */
+    lastOptimizeAt?: string | undefined;
 }
 export declare function loadProjectAgentLearningPolicy(role: string, projectRoot?: string): ProjectAgentLearningPolicy;
-export declare function updateProjectAgentLearningPolicy(role: string, patch: Partial<Pick<ProjectAgentLearningPolicy, 'enabled'>>, projectRoot?: string): ProjectAgentLearningPolicy;
+/**
+ * Merge a patch into the persisted policy.
+ *
+ * Always re-reads immediately before writing. Capture and the optimization pass
+ * both own fields in this file and run on independent schedules, so writing a
+ * whole object built from a value read earlier in the call silently reverts
+ * whatever the other one recorded in between.
+ */
+export declare function updateProjectAgentLearningPolicy(role: string, patch: Partial<ProjectAgentLearningPolicy>, projectRoot?: string): ProjectAgentLearningPolicy;
+/** Stamp the completion of an optimization pass so the cooldown can see it. */
+export declare function recordProjectAgentOptimizePass(role: string, projectRoot?: string, at?: string): void;
 //# sourceMappingURL=project-agent-learning-policy.d.ts.map

package/dist/coordination/agents/project-agent-learning-structured.d.ts

@@ -12,11 +12,58 @@ export interface StructuredLearnedEntry {
     what: string;
     /** Why this directive exists — derived from category and directive signals. */
     why: string;
-    /** Concrete, runnable anchor — commands, file paths, package names. */
+    /**
+     * Concrete, runnable anchors — commands, file paths, package names.
+     * One anchor per line, WITHOUT any list marker: the renderer owns the
+     * markup. Storing markup here is what produced the `- *How:*   - *How:*`
+     * nesting that compounded on every capture.
+     */
     how: string;
     /** ISO timestamp of when this entry was originally captured. */
     capturedAt: string;
+    /**
+     * Skill this directive develops, when capture could route it. Entries with a
+     * skill are distilled into `.wrongstack/agents/<role>/skills/<skill>.md` by
+     * the optimization pass; unrouted entries stay role-level.
+     */
+    skill?: string | undefined;
+    /**
+     * Completed tasks where this directive was injected **and** the agent's
+     * report showed it was actually exercised (its anchors or distinctive
+     * wording appeared in the output).
+     *
+     * Optional so an entry can be constructed without a track record; treat a
+     * missing value as 0 by reading it through {@link directiveTrials}.
+     */
+    applied?: number | undefined;
+    /** Of those, the ones that ended in a successful task. */
+    wins?: number | undefined;
 }
+/** Normalized track record. A missing counter reads as 0, never as NaN. */
+export declare function directiveTrials(entry: Pick<StructuredLearnedEntry, 'applied' | 'wins'>): {
+    applied: number;
+    wins: number;
+    losses: number;
+};
+/**
+ * Laplace-smoothed success rate of a directive: the fraction of tasks that
+ * succeeded among those where the directive was actually exercised.
+ *
+ * An unproven directive scores exactly 0.5 — a neutral prior, not a penalty.
+ * That matters everywhere this is used as a ranking key: "no evidence" must
+ * never sort below "evidence of harm", which is the inversion the skill-level
+ * score used to have.
+ */
+export declare function directiveUtility(entry: Pick<StructuredLearnedEntry, 'applied' | 'wins'>): number;
+/** Trials before a directive's record is trusted enough to protect or retire it. */
+export declare const DIRECTIVE_PROVEN_MIN_APPLIED = 5;
+/** Utility at or above which a directive is treated as proven. */
+export declare const DIRECTIVE_PROVEN_MIN_UTILITY = 0.7;
+/**
+ * A directive that has earned the right not to be overwritten by a near
+ * duplicate: exercised enough times, and correlated with success when it was.
+ */
+export declare function isProvenDirective(entry: StructuredLearnedEntry): boolean;
 export declare function parseLearnedEntryStamp(entry: string): {
     capturedAt: string;
     category: LearnedEntryCategory | null;
@@ -31,6 +78,30 @@ export declare function mergeStructuredEntries(existing: StructuredLearnedEntry[
     text: string;
     category: LearnedEntryCategory;
     capturedAt: string;
+    skill?: string | undefined;
 }): StructuredLearnedEntry[];
 export declare function renderLearnedInstructions(role: string, entries: StructuredLearnedEntry[], capturedAt: string): string;
+/**
+ * Keep the rendered buffer within `maxBytes` by evicting the least valuable
+ * entries: plain facts before hard-won warnings, then the worst track record,
+ * then the oldest.
+ *
+ * Track record before age is the point of the ordering. Age says when a
+ * directive arrived; utility says whether it has ever helped. A directive that
+ * has been exercised eight times and correlated with failure every time is the
+ * cheapest thing in the buffer no matter how recently it was written, and a
+ * directive that keeps working should outlive newer arrivals. Entries with no
+ * record sit at the neutral 0.5 prior, so this reduces to the previous
+ * age-ordered behaviour for any buffer that predates outcome tracking.
+ *
+ * This replaces the old "block every automatic capture once the file passes
+ * 8 KB" gate. That gate had no way to ever clear itself (consolidation wrote a
+ * separate file and never touched the raw buffer), so the roles that had
+ * learned the most were exactly the roles that had permanently stopped
+ * learning. Bounding the buffer is the same protection without the deadlock.
+ */
+export declare function enforceLearnedBudget(entries: readonly StructuredLearnedEntry[], capturedAt: string, maxBytes: number, role?: string): {
+    kept: StructuredLearnedEntry[];
+    dropped: StructuredLearnedEntry[];
+};
 //# sourceMappingURL=project-agent-learning-structured.d.ts.map

package/dist/coordination/agents/project-agent-optimizer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Learning optimization pass: raw captures → consolidated role document +
+ * per-skill project addenda → pruned capture buffer.
+ *
+ * One implementation, shared by every surface. The CLI used to build the
+ * instruction and hand it to the chat loop with nothing on the other end to
+ * persist the result, so `/agent-improve <role> consolidate` produced a wall of
+ * markdown and no state change; the WebUI had the only working pipeline.
+ */
+import type { Provider } from '../../types/index.js';
+/** Resolved model handle used for headless synthesis. */
+export interface LearningOptimizerLlm {
+    provider: Provider;
+    model: string;
+}
+export interface OptimizeLearningOptions {
+    llm?: LearningOptimizerLlm | undefined;
+    trigger?: 'manual' | 'automatic' | undefined;
+    /** Archive + reset the raw buffer after a successful pass. Default true. */
+    prune?: boolean | undefined;
+    maxTokens?: number | undefined;
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface OptimizeLearningResult {
+    role: string;
+    status: 'optimized' | 'no-entries' | 'no-llm' | 'empty-synthesis' | 'failed';
+    rawEntryCount: number;
+    /** Skills whose project addendum was refreshed by this pass. */
+    skills: string[];
+    content?: string | undefined;
+    model?: string | undefined;
+    pruned?: boolean | undefined;
+    /** Present on `no-llm`: the caller may drive the pass through a chat agent. */
+    instruction?: string | undefined;
+    error?: string | undefined;
+}
+/** Strip a whole-document code fence a model sometimes wraps output in. */
+export declare function unwrapWholeDocumentFence(text: string): string;
+/**
+ * Run the full optimization pass for one role.
+ *
+ * Without an LLM the pass degrades rather than failing: the role-level
+ * instruction is returned for a caller-driven consolidation, and each skill
+ * still gets a deterministically rendered addendum from its routed directives,
+ * so tagged learning reaches the skill layer even on a headless box.
+ */
+export declare function optimizeProjectAgentLearning(role: string, projectRoot?: string, options?: OptimizeLearningOptions): Promise<OptimizeLearningResult>;
+//# sourceMappingURL=project-agent-optimizer.d.ts.map

package/dist/coordination/agents/project-agent-quarantine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The retired-directive log, and the surgery that keeps a retired directive
+ * from surviving inside a document that was distilled while it was still
+ * believed.
+ *
+ * Retirement removes a directive from the capture buffer, but by then it may
+ * already have been folded into `skills/<skill>.md` and `consolidated.md` —
+ * both of which are injected into every spawn and neither of which is rebuilt
+ * until the next optimization pass, up to six hours later. Without the scrub
+ * below, "stops being injected" was only true of the buffer, which is the one
+ * copy the agent was least likely to be reading.
+ *
+ * Its own module so both the writer (`project-agent-directive-outcome`) and the
+ * reader (`project-agent-consolidation`, building the distillation prompt) can
+ * depend on it without depending on each other.
+ */
+import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
+/** Ceiling on the retired-directive log. Local audit only; never injected. */
+export declare const QUARANTINE_MAX_BYTES: number;
+export interface QuarantinedDirective {
+    what: string;
+    skill?: string | undefined;
+}
+export declare function quarantinePath(role: string, projectRoot?: string): string;
+/**
+ * Append retired directives to the role's log.
+ *
+ * They are kept rather than deleted: a directive can be right about a project
+ * that has since changed, and the log is the only place to see what the loop
+ * decided to stop believing.
+ */
+export declare function appendQuarantine(role: string, retired: readonly StructuredLearnedEntry[], at: string, projectRoot?: string): void;
+/** Every directive this role has retired, newest last. */
+export declare function readQuarantinedDirectives(role: string, projectRoot?: string): QuarantinedDirective[];
+/**
+ * Remove any line that states one of the retired directives, together with the
+ * indented lines that hang off it.
+ *
+ * Line-oriented rather than model-driven on purpose: this runs on the task
+ * completion path, where a provider call is not affordable and a failure to
+ * scrub means the agent keeps being told to do the thing that kept failing.
+ */
+export declare function scrubRetiredLines(text: string, retired: readonly string[]): string;
+/**
+ * Whether a scrubbed document still says anything actionable.
+ *
+ * Chrome does not count. A skill addendum keeps its title and its standing
+ * "read these as refinements of the bundled skill" blockquote no matter how
+ * many rules are removed, so testing for "any long line" would report an
+ * addendum with nothing left in it as still having content.
+ */
+export declare function hasDirectiveContent(text: string): boolean;
+/**
+ * Retired directives worth warning the distiller about: the ones it could only
+ * resurrect from an existing document.
+ *
+ * A directive the agent has since written again is deliberately excluded. The
+ * whole reason retirement archives rather than deletes is that a rule can be
+ * right about a project that has since changed; if the role re-learned it, it
+ * is back in the buffer with a fresh record and has earned its second chance.
+ */
+export declare function retiredDirectivesToWarnAbout(role: string, currentDirectives: readonly string[], projectRoot?: string, skill?: string): string[];
+//# sourceMappingURL=project-agent-quarantine.d.ts.map