@wrongstack/core 0.302.0 → 0.303.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,30 @@ 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[];
 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-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 { validateProjectAgentConfig } from './project-agent-config-validation.js';
+export { loadProjectAgentConfig } from './project-agent-config-io.js';
+export { CAPTURE_SESSION_WINDOW_MS, resetCaptureWindow, resetCaptureWindows, } from './project-agent-capture-window.js';
+export { CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION };
+export { buildSkillDistillInstruction, clearProjectSkillAugmentation, DEFAULT_EAGER_SKILL_LIMIT, listProjectSkillAugmentations, loadProjectSkillAugmentation, loadSkillAffinity, rankRoleSkills, recordSkillLoad, recordSkillOutcome, renderSkillAugmentation, resolveRoleSkillCandidates, routeDirectiveToSkill, saveProjectSkillAugmentation, setSkillPinned, SKILL_AUGMENTATION_MAX_BYTES, type SkillAffinity, type SkillAffinityEntry, } from './project-agent-skill-layer.js';
+export { readRawLearnedEntries, type SaveConsolidationOptions } from './project-agent-consolidation.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 { type LearningOptimizerLlm, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, unwrapWholeDocumentFence, } from './project-agent-optimizer.js';
 export { buildConsolidationInstruction, type ConsolidationMetadata, clearProjectAgentConsolidated, isConsolidated, loadConsolidationMetadata, loadProjectAgentConsolidated, saveProjectAgentConsolidated, } from './project-agent-consolidation.js';
 export type { CreateProjectAgentInput, LearnedCaptureResult, ProjectAgentConfig, ProjectAgentProfile, RoleKnowledgeManifest, } from './project-agent-identity-types.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 { decomposeLearnedEntry, enforceLearnedBudget, mergeStructuredEntries, parseLearnedEntryStamp, renderLearnedInstructions, type StructuredLearnedEntry, } from './project-agent-learning-structured.js';
 export { assertProjectAgentRole } from './project-agent-paths.js';
+export { splitLearnedEntries, tokenOverlap } from './project-agent-learning-entries.js';
+export { parseStructuredLearnedEntriesFromContent } from './project-agent-learning-structured.js';
 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,10 @@ 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;
 }
 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-structured.d.ts

@@ -12,10 +12,21 @@ 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;
 }
 export declare function parseLearnedEntryStamp(entry: string): {
     capturedAt: string;
@@ -31,6 +42,21 @@ 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 — oldest first, plain facts before hard-won warnings.
+ *
+ * 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-skill-layer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Project-specific **skill development** layer for roster agents.
+ *
+ * This is deliberately not a memory store. A roster agent's skills are what it
+ * knows how to *do*; this layer lets a project grow those skills in place — the
+ * bundled `testing` skill body, plus everything this project has taught the
+ * `verifier` agent about testing *here*. The addendum is injected directly
+ * beneath the bundled skill body at spawn time, so the agent reads one coherent
+ * skill rather than a skill plus a pile of recalled facts.
+ *
+ * Files under `.wrongstack/agents/<role>/skills/`:
+ *   `<skill>.md`    — project addendum for that skill (distilled, bounded)
+ *   `affinity.json` — per-skill load/outcome/learning counters that drive which
+ *                     skills are eagerly loaded for this role in this project
+ *
+ * Ownership: capture routes each learned directive to a skill
+ * (`project-agent-identity.ts`); the optimization pass distills the routed
+ * directives into `<skill>.md`; the spawn path reads both
+ * (`packages/cli/src/fleet/host-context.ts`).
+ */
+/** Hard cap on a single skill addendum. Keeps the spawn budget predictable. */
+export declare const SKILL_AUGMENTATION_MAX_BYTES = 6144;
+/** Default number of skills eagerly loaded into a spawn. */
+export declare const DEFAULT_EAGER_SKILL_LIMIT = 3;
+export declare function isProjectSkillName(name: string): boolean;
+export declare function assertProjectSkillName(name: string): string;
+export declare function projectSkillsDir(role: string, projectRoot?: string): string;
+export declare function projectSkillAugmentationPath(role: string, skill: string, projectRoot?: string): string;
+export declare function projectSkillAffinityPath(role: string, projectRoot?: string): string;
+export declare function loadProjectSkillAugmentation(role: string, skill: string, projectRoot?: string): string;
+export declare function saveProjectSkillAugmentation(role: string, skill: string, content: string, projectRoot?: string): string;
+export declare function clearProjectSkillAugmentation(role: string, skill?: string, projectRoot?: string): void;
+/** Skill names that have a project addendum for this role. */
+export declare function listProjectSkillAugmentations(role: string, projectRoot?: string): string[];
+/**
+ * Render a distilled skill addendum. Used as the deterministic fallback when
+ * no LLM is available — the directives are already instructive, so emitting
+ * them verbatim under a stable header is strictly better than no addendum.
+ */
+export declare function renderSkillAugmentation(role: string, skill: string, directives: readonly string[], updatedAt: string): string;
+/**
+ * Instruction for the optimization pass: turn the directives that capture
+ * routed to one skill into that skill's project addendum.
+ */
+export declare function buildSkillDistillInstruction(role: string, skill: string, directives: readonly string[], existing?: string): string;
+export interface SkillAffinityEntry {
+    /** Times this skill was eagerly loaded into a spawn of this role. */
+    loaded: number;
+    /** Task outcomes observed while this skill was loaded. */
+    succeeded: number;
+    failed: number;
+    /** Learned directives routed to this skill. */
+    learned: number;
+    lastUsedAt?: string | undefined;
+    /** Operator pin — always selected, never rotated out. */
+    pinned?: boolean | undefined;
+}
+export interface SkillAffinity {
+    role: string;
+    entries: Record<string, SkillAffinityEntry>;
+    updatedAt: string;
+}
+export declare function loadSkillAffinity(role: string, projectRoot?: string): SkillAffinity;
+/** Record that these skills were loaded into a spawn of `role`. */
+export declare function recordSkillLoad(role: string, skills: readonly string[], projectRoot?: string): void;
+/** Record the outcome of a task that ran with these skills loaded. */
+export declare function recordSkillOutcome(role: string, skills: readonly string[], ok: boolean, projectRoot?: string): void;
+/** Record that a learned directive was routed to this skill. */
+export declare function recordSkillLearned(role: string, skill: string, projectRoot?: string): void;
+export declare function setSkillPinned(role: string, skill: string, pinned: boolean, projectRoot?: string): SkillAffinity;
+/**
+ * Score a skill for this role. Higher wins. Deterministic and monotone:
+ * with no recorded history every candidate scores the same, so ranking falls
+ * back to the curated order and behaviour matches a fresh project exactly.
+ */
+export declare function scoreSkillAffinity(entry: SkillAffinityEntry | undefined): number;
+/**
+ * Rank the candidate skills for a role by project affinity, keeping the
+ * curated order as a stable tie-break, and return at most `limit` names.
+ *
+ * A skill that has accumulated project-specific learning outranks one that has
+ * not: the whole point of the layer is that a skill the project actually
+ * developed is more valuable here than a generic sibling.
+ */
+export declare function rankRoleSkills(role: string, candidates: readonly string[], projectRoot?: string, limit?: number): string[];
+/**
+ * Every skill this role could legitimately develop in this project:
+ * the project override when present, otherwise the curated catalog set (or the
+ * base role's set for a project-created role), always unioned with any skill
+ * that already carries a project addendum.
+ */
+export declare function resolveRoleSkillCandidates(role: string, projectRoot?: string): string[];
+/** Explicit tag form the agent can use: `## LEARNED [skill: testing]`. */
+export declare const LEARNED_SKILL_TAG: RegExp;
+/**
+ * Route a captured directive to one of the role's candidate skills.
+ * Returns `undefined` when nothing matches well enough — an unrouted directive
+ * stays role-level rather than being forced into the wrong skill.
+ */
+export declare function routeDirectiveToSkill(text: string, candidates: readonly string[]): string | undefined;
+//# sourceMappingURL=project-agent-skill-layer.d.ts.map

package/dist/coordination/agents/role-skills.d.ts

@@ -97,6 +97,16 @@ export declare const ROLE_SKILL_SETS: {
 export type CatalogRoleWithSkills = keyof typeof ROLE_SKILL_SETS;
 /** Standalone operational role that lives outside the phase catalog. */
 export declare const SHADOW_AGENT_SKILLS: ("api-design" | "audit-log" | "bug-hunter" | "chimera" | "data-governance" | "docker-deploy" | "git-flow" | "mnemosyne" | "multi-agent" | "node-modern" | "observability" | "output-standards" | "plugin-author" | "prompt-engineering" | "react-modern" | "refactor-planner" | "research-web" | "sdd" | "security-scanner" | "skill-creator" | "tech-stack" | "testing" | "typescript-strict" | "wrongstack-mailbox")[];
-/** Attach a bounded, fresh skill-name array so catalog templates remain mutation-safe. */
+export declare const MAX_EAGER_ROSTER_SKILLS = 3;
+/**
+ * Attach a bounded, fresh skill-name array so catalog templates remain
+ * mutation-safe.
+ *
+ * `skillNames` stays capped at `MAX_EAGER_ROSTER_SKILLS` — it is the default
+ * eager set for a project with no learning history. The full curated set is
+ * also carried as `skillPool` so the spawn path can rank *all* candidates by
+ * project affinity instead of being permanently limited to whichever three
+ * happened to be written first in this file.
+ */
 export declare function assignSkillsToAgents(definitions: readonly AgentDefinition[]): AgentDefinition[];
 //# sourceMappingURL=role-skills.d.ts.map

package/dist/coordination/index.d.ts

@@ -1,6 +1,6 @@
 export { createMessage, InMemoryAgentBridge, InMemoryBridgeTransport, } from './agent-bridge.js';
 export { type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, makeAgentSubagentRunner, withDisabledToolFiltering, } from './agent-subagent-runner.js';
-export { AGENT_CATALOG, AGENTS_BY_PHASE, type AgentBudgetTier, type AgentCapability, type AgentDefinition, type AgentPhase, ALL_AGENT_DEFINITIONS, applyProjectAgentConfig, assertProjectAgentRole, BUILD_AGENTS, buildConsolidationInstruction, buildProjectContextualizedPrompt, CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION, type ConsolidationMetadata, type CreateProjectAgentInput, canCaptureNewLearned, captureLearnedFromAgentOutput, captureLearnedFromAgentOutputDetailed, clearProjectAgentConsolidated, createProjectAgent, createProjectAgentRoster, DELIVERY_AGENTS, DISCOVERY_AGENTS, DOMAIN_AGENTS, detectLearnedConflicts, getAgentDefinition, getProjectAgentLearnStats, HEAVY_BUDGET, hintLearnedNeedsSummarization, isConsolidated, KNOWLEDGE_AGENTS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedCaptureResult, LIGHT_BUDGET, listProjectAgentLearnedEntries, listProjectAgentRoles, loadConsolidationMetadata, loadProjectAgentConfig, loadProjectAgentConsolidated, loadProjectAgentIdentity, loadProjectAgentLearned, loadProjectAgentLearningPolicy, loadProjectAgentProfile, loadRoleKnowledgeManifest, MEDIUM_BUDGET, META_AGENTS, PLANNING_AGENTS, type ProjectAgentConfig, type ProjectAgentLearningPolicy, type ProjectAgentProfile, REVIEW_AGENTS, type RoleKnowledgeManifest, refreshProjectAgentIdentity, resetProjectAgentIdentity, saveProjectAgentConsolidated, slugifyProjectAgentRole, updateProjectAgentConfig, updateProjectAgentIdentity, updateProjectAgentKnowledge, updateProjectAgentLearned, updateProjectAgentLearningPolicy, VERIFY_AGENTS, validateProjectAgentConfig, } from './agents/index.js';
+export { AGENT_CATALOG, AGENTS_BY_PHASE, type AgentBudgetTier, type AgentCapability, type AgentDefinition, type AgentPhase, ALL_AGENT_DEFINITIONS, applyProjectAgentConfig, assertProjectAgentRole, BUILD_AGENTS, buildConsolidationInstruction, buildProjectContextualizedPrompt, buildSkillDistillInstruction, CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION, CAPTURE_SESSION_WINDOW_MS, type ConsolidationMetadata, type CreateProjectAgentInput, canCaptureNewLearned, captureLearnedFromAgentOutput, captureLearnedFromAgentOutputDetailed, clearProjectAgentConsolidated, clearProjectSkillAugmentation, createProjectAgent, createProjectAgentRoster, DEFAULT_EAGER_SKILL_LIMIT, DELIVERY_AGENTS, DISCOVERY_AGENTS, DOMAIN_AGENTS, detectLearnedConflicts, getAgentDefinition, getProjectAgentLearnStats, HEAVY_BUDGET, hintLearnedNeedsSummarization, isConsolidated, KNOWLEDGE_AGENTS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedCaptureResult, type AutoOptimizeDecision, type AutoOptimizeEvent, type AutoOptimizePolicy, type AutoOptimizePolicyOverrides, DEFAULT_AUTO_OPTIMIZE_POLICY, evaluateAutoOptimize, LearningOptimizationScheduler, type LearningOptimizationSchedulerOptions, resolveAutoOptimizePolicy, type LearningOptimizerLlm, LIGHT_BUDGET, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, unwrapWholeDocumentFence, listProjectAgentLearnedEntries, listProjectAgentRoles, listProjectSkillAugmentations, loadConsolidationMetadata, loadProjectAgentConfig, loadProjectAgentConsolidated, loadProjectAgentIdentity, loadProjectAgentLearned, loadProjectAgentLearningPolicy, loadProjectAgentProfile, loadProjectSkillAugmentation, loadRoleKnowledgeManifest, loadSkillAffinity, MEDIUM_BUDGET, META_AGENTS, PLANNING_AGENTS, type ProjectAgentConfig, type ProjectAgentLearningPolicy, type ProjectAgentProfile, REVIEW_AGENTS, type RoleKnowledgeManifest, rankRoleSkills, readRawLearnedEntries, recordSkillLoad, recordSkillOutcome, refreshProjectAgentIdentity, renderSkillAugmentation, resetCaptureWindow, resetCaptureWindows, resetProjectAgentIdentity, resolveRoleSkillCandidates, routeDirectiveToSkill, SKILL_AUGMENTATION_MAX_BYTES, type SaveConsolidationOptions, type SkillAffinity, type SkillAffinityEntry, saveProjectAgentConsolidated, saveProjectSkillAugmentation, setSkillPinned, slugifyProjectAgentRole, updateProjectAgentConfig, updateProjectAgentIdentity, updateProjectAgentKnowledge, updateProjectAgentLearned, updateProjectAgentLearningPolicy, VERIFY_AGENTS, validateProjectAgentConfig, } from './agents/index.js';
 export { type AutoExtendCeiling, type AutoExtendPolicy, attachAutoExtend, } from './auto-extend.js';
 export { type BrainArbiter, type BrainDecision, type BrainDecisionOption, BrainDecisionQueue, type BrainDecisionRequest, type BrainDecisionSource, type BrainEscalationMode, type BrainFallback, type BrainRisk, DefaultBrainArbiter, type DefaultBrainArbiterOptions, EscalationRoutingBrainArbiter, formatHumanPrompt, HumanEscalatingBrainArbiter, ObservableBrainArbiter, terminalPolicyDecision, } from './brain.js';
 export { BrainDecisionLedger, type BrainDecisionLedgerOptions, type BrainLedgerEntry, brainDecisionKey, createLedgerGuardBrainArbiter, type LedgerGuardBrainArbiterOptions, } from './brain-ledger.js';