@wrongstack/core 0.302.2 → 0.305.0

package/dist/coordination/agents/project-agent-skill-layer.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ *
+ * `existing` is **not optional in practice**: this renderer only ever sees the
+ * directives currently sitting in the capture buffer, and the buffer is pruned
+ * after every successful optimization. Rendering from the buffer alone and
+ * writing the result over the file therefore deleted every directive distilled
+ * by an earlier pass. That happened silently on any headless box, and on a
+ * model-backed one whenever a single per-skill call timed out and the role-level
+ * consolidation then pruned; the only remaining copy was under `archive/`.
+ *
+ * Passing the current addendum in keeps it: prior body first, new directives
+ * appended, near-duplicates of lines already present dropped.
+ */
+export declare function renderSkillAugmentation(role: string, skill: string, directives: readonly string[], updatedAt: string, existing?: 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, retired?: readonly 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.
+ *
+ * Also stamps `lastUsedAt`: an outcome is the strongest evidence that a skill
+ * was in use, and the recency decay in {@link scoreSkillAffinity} reads that
+ * stamp. Leaving it to `recordSkillLoad` alone meant an affinity file written
+ * only through this path looked like it had never been touched.
+ */
+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;
+/** Half-life of outcome evidence, in days. Older evidence fades toward neutral. */
+export declare const SKILL_EVIDENCE_HALF_LIFE_DAYS = 30;
+/**
+ * Score a skill for this role. Higher wins. Deterministic and monotone: with no
+ * recorded history every candidate scores exactly the same, so ranking falls
+ * back to the curated order and a fresh project behaves as if this layer did
+ * not exist.
+ *
+ * Four properties the previous scoring got wrong, each of which showed up as a
+ * skill that could not be dislodged:
+ *
+ * 1. **Failure counts against a skill.** The old form skipped Laplace smoothing
+ *    when there were no outcomes, so "no evidence" scored 0 while ten straight
+ *    failures scored 0.25 — failure ranked as evidence of relevance. The
+ *    success rate is now centred on the 0.5 prior, so a losing record is
+ *    negative and an untried skill is exactly neutral.
+ * 2. **Exposure is not merit.** `min(loaded, 10) * 0.1` paid a skill up to a
+ *    full point for having been selected, which is a loop: selected skills
+ *    out-scored unselected ones because they had been selected. The term is now
+ *    an exploration bonus that *decays* with load count, so a skill that has
+ *    never been tried is the one with something to prove.
+ * 3. **Evidence goes stale.** Counters are lifetime totals; a project that
+ *    switched test runners four months ago still carried the old runner's wins
+ *    at full weight. Outcome evidence now decays with a
+ *    {@link SKILL_EVIDENCE_HALF_LIFE_DAYS}-day half-life.
+ * 4. **One chatty skill could pin the top slot.** `learned * 2` is unbounded, so
+ *    a skill that attracts routing dominates every other signal forever. It is
+ *    now logarithmic: still the strongest single term, no longer a lock.
+ *
+ * A missing `lastUsedAt` means "unknown", not "ancient" — legacy affinity files
+ * written before the field existed must not have their evidence zeroed.
+ */
+export declare function scoreSkillAffinity(entry: SkillAffinityEntry | undefined, now?: number): 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/agents/types.d.ts

@@ -91,8 +91,16 @@ export declare const TOOLS: {
     readonly write: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "mailbox"];
     /** Full build loop: edit + run (lint/format/typecheck/test/bash). */
     readonly build: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "bash", "exec", "lint", "format", "typecheck", "test", "mailbox"];
-    /** Version control. */
-    readonly vcs: readonly ["read", "grep", "glob", "git", "diff"];
+    /**
+     * Version control.
+     *
+     * `mailbox` is in every preset on purpose: a subagent that hits a wall must
+     * be able to say so. This was the one preset without it, which left the `git`
+     * and `release` roles able to fail but not to ask — the two roles whose work
+     * most often needs a decision from the leader (force-push, tag collision,
+     * dirty tree) and least often has a safe default.
+     */
+    readonly vcs: readonly ["read", "grep", "glob", "git", "diff", "mailbox"];
     /** Dependency management + CVE audit. */
     readonly deps: readonly ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"];
     /** Documentation authoring. */

package/dist/coordination/director-prompts.d.ts

@@ -101,13 +101,22 @@ export interface SubagentPromptParts {
  */
 export declare function composeSubagentPrompt(parts?: SubagentPromptParts): string;
 /**
- * Render a short bullet list summarising a roster — useful for stuffing
- * into `composeDirectorPrompt({ rosterSummary })` so the director model
- * can see available roles without scanning tool descriptions.
+ * Render a bullet list summarising a roster — stuffed into
+ * `composeDirectorPrompt({ rosterSummary })` so the leader can see the roles it
+ * may spawn without scanning tool descriptions.
  *
- * Each entry: `- <role-id>: <name>[ (provider/model)] — <prompt-headline>`
- * The prompt headline is the first non-empty line of `config.prompt`,
- * truncated to 80 chars. Skipped entirely when the role has no prompt.
+ * Each entry: `- <role-id>[ (<name>)][ (provider/model)] — <capability>`
+ *
+ * The capability comes from `dispatch.summary`, the curated one-liner the
+ * catalog already writes for every agent and the dispatcher already routes on.
+ * It used to come from the first 80 characters of `config.prompt`, which is
+ * how a 77-role menu came to read as 77 variations of "You are the X agent.
+ * Your job is…" with the discriminating half cut off. A leader given that list
+ * can only reliably pick the roles whose id spells out the job — and the usage
+ * data matched exactly that: 57 of the 77 roles had never once been chosen.
+ *
+ * The prompt headline stays as the fallback for roles with no dispatch
+ * metadata, so a hand-written project role is still listed.
  */
 export declare function rosterSummaryFromConfigs(roster: Record<string, {
     name: string;
@@ -115,5 +124,9 @@ export declare function rosterSummaryFromConfigs(roster: Record<string, {
     model?: string | undefined;
     prompt?: string | undefined;
     role?: string | undefined;
+    dispatch?: {
+        summary: string;
+        keywords: string[];
+    } | undefined;
 }>): string;
 //# sourceMappingURL=director-prompts.d.ts.map

package/dist/coordination/director-tools.d.ts

@@ -1,9 +1,9 @@
 import type { SubagentConfig } from '../types/multi-agent.js';
 import type { Tool } from '../types/tool.js';
 import type * as Host from './director-host-contracts.js';
-export { makeQualityGateTool } from './director-quality-gate-tool.js';
-export { makeCollabDebugTool, makeFleetEmitTool, makeWorkCompleteTool, } from './director-collab-tools.js';
 export { makeAskResultTool, makeAskTool, makeAssignTool, makeAwaitTasksTool, makeFleetTool, makeRollUpTool, makeTerminateAllTool, makeTerminateTool, } from './director-basic-tools.js';
+export { makeCollabDebugTool, makeFleetEmitTool, makeWorkCompleteTool, } from './director-collab-tools.js';
+export { makeQualityGateTool } from './director-quality-gate-tool.js';
 export declare function makeSpawnTool(director: Host.DirectorAdmissionPort, roster?: Record<string, SubagentConfig>): Tool;
 export declare function makeKanbanQueueTool(director: Host.DirectorLeaseRecoveryPort, roster?: Record<string, SubagentConfig>): Tool;
 //# sourceMappingURL=director-tools.d.ts.map

package/dist/coordination/fleet.d.ts

@@ -26,12 +26,6 @@ export declare const REFACTOR_PLANNER_AGENT: SubagentConfig;
 export declare const SECURITY_SCANNER_AGENT: SubagentConfig;
 /** Generic template used directly or cloned into project-specific roles. */
 export declare const GENERIC_AGENT: SubagentConfig;
-/**
- * All agents in a map for easy lookup by role. The 75-role phase catalog
- * (`ALL_AGENT_DEFINITIONS`) already includes `critic` and the historical
- * audit/review specialists. Adding standalone `generic` and `shadow-agent`
- * roles produces 77 unique built-in role ids.
- */
 export declare const FLEET_ROSTER: Record<string, SubagentConfig>;
 export interface FleetRosterBudget {
     timeoutMs?: number | undefined;

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, type AutoOptimizeDecision, type AutoOptimizeEvent, type AutoOptimizePolicy, type AutoOptimizePolicyOverrides, 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, consolidatedDocumentPath, createProjectAgent, createProjectAgentRoster, DEFAULT_AUTO_OPTIMIZE_POLICY, DEFAULT_EAGER_SKILL_LIMIT, DELIVERY_AGENTS, DIRECTIVE_QUARANTINE_MAX_UTILITY, DIRECTIVE_QUARANTINE_MIN_APPLIED, DISCOVERY_AGENTS, type DirectiveOutcomeResult, DOMAIN_AGENTS, detectLearnedConflicts, directiveTrials, directiveUtility, directiveWasApplied, evaluateAutoOptimize, getAgentDefinition, getProjectAgentLearnStats, HEAVY_BUDGET, hintLearnedNeedsSummarization, isConsolidated, isProvenDirective, KNOWLEDGE_AGENTS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedCaptureResult, LearningOptimizationScheduler, type LearningOptimizationSchedulerOptions, type LearningOptimizerLlm, LIGHT_BUDGET, listProjectAgentLearnedEntries, listProjectAgentRoles, listProjectSkillAugmentations, loadConsolidationMetadata, loadProjectAgentConfig, loadProjectAgentConsolidated, loadProjectAgentIdentity, loadProjectAgentLearned, loadProjectAgentLearningPolicy, loadProjectAgentProfile, loadProjectSkillAugmentation, loadRoleKnowledgeManifest, loadSkillAffinity, MEDIUM_BUDGET, META_AGENTS, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, PLANNING_AGENTS, type ProjectAgentConfig, type ProjectAgentLearningPolicy, type ProjectAgentProfile, type QuarantinedDirective, quarantinePath, REVIEW_AGENTS, type RoleKnowledgeManifest, rankRoleSkills, readQuarantinedDirectives, readRawLearnedEntries, recordDirectiveOutcomes, recordSkillLoad, recordSkillOutcome, refreshProjectAgentIdentity, renderSkillAugmentation, resetCaptureWindow, resetCaptureWindows, resetProjectAgentIdentity, resolveAutoOptimizePolicy, resolveRoleSkillCandidates, retiredDirectivesToWarnAbout, routeDirectiveToSkill, type SaveConsolidationOptions, SKILL_AUGMENTATION_MAX_BYTES, type SkillAffinity, type SkillAffinityEntry, saveProjectAgentConsolidated, saveProjectSkillAugmentation, scoreSkillAffinity, scrubRetiredLines, setSkillPinned, slugifyProjectAgentRole, unwrapWholeDocumentFence, 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';