opencode-matrixx 2.6.10 → 2.6.12

package/dist/config/schema/tool-gating.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+/** Startup-token tool auto-gating — defer rarely-needed LLM tools until auto-detect or opt-in */
+export declare const ToolGatingConfigSchema: z.ZodObject<{
+    bdd_tools: z.ZodOptional<z.ZodBoolean>;
+    pdf_figures: z.ZodOptional<z.ZodBoolean>;
+    look_at: z.ZodOptional<z.ZodBoolean>;
+    preset_tools: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ToolGatingConfig = z.infer<typeof ToolGatingConfigSchema>;

package/dist/config/schema.d.ts

@@ -13,9 +13,9 @@ export * from "./schema/context-mode";
 export * from "./schema/dcp";
 export * from "./schema/evolution";
 export * from "./schema/experimental";
-export * from "./schema/failure-counter";
 export * from "./schema/headroom";
 export * from "./schema/hooks";
+export * from "./schema/knowledge";
 export * from "./schema/matrix-loop";
 export * from "./schema/matrixx-config";
 export * from "./schema/matrixx-self-config";
@@ -32,4 +32,5 @@ export * from "./schema/task";
 export * from "./schema/tasks";
 export * from "./schema/tdd-enforcer";
 export * from "./schema/tmux";
+export * from "./schema/tool-gating";
 export * from "./schema/websearch";

package/dist/create-hooks.d.ts

@@ -29,6 +29,7 @@ export declare function createHooks(args: {
     inputSecretGuard: ReturnType<typeof import("./hooks").createInputSecretGuardHook> | null;
     keywordDetector: ReturnType<typeof import("./hooks").createKeywordDetectorHook> | null;
     contextInjectorMessagesTransform: ReturnType<typeof import("./features/context-injector").createContextInjectorMessagesTransformHook>;
+    knowledgeHubInjector: ReturnType<typeof import("./hooks").createKnowledgeHubInjectorHook> | null;
     envContextInjector: ReturnType<typeof import("./hooks").createEnvContextInjectorHook> | null;
     thinkingBlockValidator: ReturnType<typeof import("./hooks").createThinkingBlockValidatorHook> | null;
     toolPairValidator: ReturnType<typeof import("./hooks").createToolPairValidatorHook> | null;
@@ -49,11 +50,12 @@ export declare function createHooks(args: {
     contextModeEnforcer: ReturnType<typeof import("./hooks").createContextModeEnforcerHook> | null;
     readImageResizer: ReturnType<typeof import("./hooks").createReadImageResizerHook> | null;
     webfetchRedirectGuard: ReturnType<typeof import("./hooks").createWebFetchRedirectGuardHook> | null;
-    hashlineEditDiffEnhancer: ReturnType<typeof import("./hooks").createHashlineEditDiffEnhancerHook> | null;
     qualityGate: ReturnType<typeof import("./hooks").createQualityGateHook> | null;
     taskNotepad: ReturnType<typeof import("./hooks").createTaskNotepadHook> | null;
     taskEditGuard: ReturnType<typeof import("./hooks").createTaskEditGuardHook> | null;
     documentReaderGuard: ReturnType<typeof import("./hooks").createDocumentReaderGuardHook> | null;
+    knowledgeHubGuard: ReturnType<typeof import("./hooks").createKnowledgeHubGuardHook> | null;
+    knowledgeHubSearchNudge: ReturnType<typeof import("./hooks").createKnowledgeHubSearchNudgeHook> | null;
     evolutionWatcher: ReturnType<typeof import("./hooks").createEvolutionWatcherHook> | null;
     contextWindowMonitor: ReturnType<typeof import("./hooks").createContextWindowMonitorHook> | null;
     preemptiveCompaction: ReturnType<typeof import("./hooks").createPreemptiveCompactionHook> | null;
@@ -68,7 +70,6 @@ export declare function createHooks(args: {
     matrixLoop: ReturnType<typeof import("./hooks").createMatrixLoopHook> | null;
     editErrorRecovery: ReturnType<typeof import("./hooks").createEditErrorRecoveryHook> | null;
     delegateTaskRetry: ReturnType<typeof import("./hooks").createDelegateTaskRetryHook> | null;
-    failureCounter: ReturnType<typeof import("./hooks").createFailureCounterHook> | null;
     startWork: ReturnType<typeof import("./hooks").createStartWorkHook> | null;
     oracleMdOnly: ReturnType<typeof import("./hooks").createOracleMdOnlyHook> | null;
     mouseNotepad: ReturnType<typeof import("./hooks").createMouseNotepadHook> | null;

package/dist/features/background-agent/manager.d.ts

@@ -184,6 +184,25 @@ export declare class BackgroundManager {
      * Returns the number of tasks cancelled.
      */
     cancelAllForSession(parentSessionID: string): number;
+    /**
+     * Wait for all descendant tasks (running/pending) to reach a terminal state.
+     * Polls every `pollIntervalMs` until all tasks are terminal or `timeoutMs` elapses.
+     * Returns per-task results: completed tasks and timed-out (still running) tasks.
+     */
+    waitForAllDescendants(sessionID: string, timeoutMs?: number, pollIntervalMs?: number): Promise<{
+        completed: Array<{
+            id: string;
+            description: string;
+            agent: string;
+            status: string;
+        }>;
+        timedOut: Array<{
+            id: string;
+            description: string;
+            agent: string;
+            status: string;
+        }>;
+    }>;
     private startPolling;
     private stopPolling;
     private registerProcessCleanup;

package/dist/features/bdd/schema.d.ts

@@ -86,8 +86,8 @@ export declare const HttpMethodSchema: z.ZodEnum<{
 }>;
 export declare const ResponseFormatSchema: z.ZodEnum<{
     binary: "binary";
-    text: "text";
     json: "json";
+    text: "text";
     html: "html";
     xml: "xml";
 }>;
@@ -118,8 +118,8 @@ export declare const ApiResponseSchema: z.ZodObject<{
     status: z.ZodNumber;
     format: z.ZodEnum<{
         binary: "binary";
-        text: "text";
         json: "json";
+        text: "text";
         html: "html";
         xml: "xml";
     }>;
@@ -174,8 +174,8 @@ export declare const ApiAnnotationsSchema: z.ZodObject<{
         status: z.ZodNumber;
         format: z.ZodEnum<{
             binary: "binary";
-            text: "text";
             json: "json";
+            text: "text";
             html: "html";
             xml: "xml";
         }>;
@@ -236,8 +236,8 @@ export declare const ContractAnnotationsSchema: z.ZodObject<{
             status: z.ZodNumber;
             format: z.ZodEnum<{
                 binary: "binary";
-                text: "text";
                 json: "json";
+                text: "text";
                 html: "html";
                 xml: "xml";
             }>;
@@ -366,8 +366,8 @@ export declare const ContractSchema: z.ZodObject<{
                 status: z.ZodNumber;
                 format: z.ZodEnum<{
                     binary: "binary";
-                    text: "text";
                     json: "json";
+                    text: "text";
                     html: "html";
                     xml: "xml";
                 }>;

package/dist/features/builtin-commands/templates/evolution.d.ts

@@ -1 +1 @@
-export declare const EVOLUTION_TEMPLATE = "# Evolution Command\n\n## Purpose\n\nManage self-evolution proposals staged in `.matrixx/evolution/pending`.\n\n## Commands\n\n- `/evolution list` \u2014 list pending proposals\n- `/evolution approve <slug>` \u2014 promote pending skill to `.opencode/skills/<slug>/SKILL.md`\n- `/evolution reject <slug>` \u2014 discard pending proposal\n- `/evolution audit` \u2014 show last 20 audit entries\n\n---\n\n# PHASE 1: PARSE ARGUMENTS\n\nArguments: $ARGUMENTS\n\n- If empty or \"list\": list pending\n- If \"approve <slug>\" or \"approve <slug> --global\": promote\n- If \"reject <slug>\": discard\n- If \"audit\" or \"log\": show audit\n- Otherwise: show help and list pending\n\n---\n\n# PHASE 2: EXECUTE\n\n## List\n\nUse bash: `ls -1 .matrixx/evolution/pending/*.md 2>/dev/null | xargs -I {} basename {} .md` or `rtk ls .matrixx/evolution/pending`\nFor each slug, read `.matrixx/evolution/pending/<slug>.meta.json` to show confidence, version, derived_from.\nIf none: \"No pending evolution proposals.\"\n\n## Approve\n\n1. Verify `.matrixx/evolution/pending/<slug>.md` exists \u2014 if not, error: \"Pending <slug> not found. Run /evolution list to see available.\"\n2. Copy staged skill:\n   - `mkdir -p .opencode/skills/<slug>`\n   - `cp .matrixx/evolution/pending/<slug>.md .opencode/skills/<slug>/SKILL.md`\n   - Also preserve versioned copy: `mkdir -p .matrixx/evolution/skills/<slug>/versions && cp .matrixx/evolution/pending/<slug>.md .matrixx/evolution/skills/<slug>/SKILL.md`\n3. Append audit: `echo '{\"action\":\"promoted\",\"slug\":\"<slug>\",\"timestamp\":\"'$(date -Iseconds)'\"}' >> .matrixx/evolution/audit.log`\n4. Remove pending: `rm .matrixx/evolution/pending/<slug>.md .matrixx/evolution/pending/<slug>.meta.json`\n5. If argument includes --global, also copy to `~/.agents/skills/<slug>/SKILL.md`\n6. Confirm: \"Promoted <slug> to .opencode/skills/<slug>/SKILL.md \u2014 will be loaded on next session start.\"\n\n## Reject\n\n1. Verify pending exists\n2. `rm .matrixx/evolution/pending/<slug>.md .matrixx/evolution/pending/<slug>.meta.json`\n3. Append audit with action rejected\n4. Confirm: \"Rejected <slug>.\"\n\n## Audit\n\nRead `.matrixx/evolution/audit.log` last 20 lines: `tail -n 20 .matrixx/evolution/audit.log 2>/dev/null || echo \"No audit entries.\"`\n\n---\n\n# CONSTRAINTS\n\n- Use bash/rtk for file ops \u2014 no dedicated evolution tool yet\n- Never invent slug \u2014 read from pending dir\n- Keep operations atomic; report errors clearly\n- Do not modify pending content \u2014 promote as-is after human review\n";
+export declare const EVOLUTION_TEMPLATE = "# Evolution Command\n\n## Purpose\n\nManage self-evolution proposals staged in `.matrixx/evolution/pending`.\n\n## Commands\n\n- `/evolution list` \u2014 list pending proposals\n- `/evolution approve <slug>` \u2014 promote pending skill to `.opencode/skills/<slug>/SKILL.md`\n- `/evolution reject <slug>` \u2014 discard pending proposal\n- `/evolution audit` \u2014 show last 20 audit entries\n\n---\n\n# PHASE 1: PARSE ARGUMENTS\n\nArguments: $ARGUMENTS\n\n- If empty or \"list\": list pending\n- If \"approve <slug>\" or \"approve <slug> --global\": promote\n- If \"reject <slug>\": discard\n- If \"audit\" or \"log\": show audit\n- Otherwise: show help and list pending\n\n---\n\n# PHASE 2: EXECUTE\n\nUse the `evolution` tool for every operation below \u2014 never shell out for\nevolution state. Parse $ARGUMENTS into one tool call per user request.\n\n## List\n\nCall `evolution` with `{ \"action\": \"list\" }`.\nFor each slug, call `evolution` with `{ \"action\": \"get\", \"slug\": \"<slug>\" }` to show confidence, version, derived_from.\nIf none: \"No pending evolution proposals.\"\n\n## Approve\n\n1. Call `evolution` with `{ \"action\": \"get\", \"slug\": \"<slug>\" }` \u2014 if not found, error: \"Pending <slug> not found. Run /evolution list to see available.\"\n2. Call `evolution` with `{ \"action\": \"approve\", \"slug\": \"<slug>\" }` to promote the staged skill (audit entry recorded by the tool).\n3. If argument includes --global, call `evolution` with `{ \"action\": \"approve\", \"slug\": \"<slug>\", \"global\": true }` instead to also copy to `~/.agents/skills/<slug>/SKILL.md`.\n4. Confirm: \"Promoted <slug> to .opencode/skills/<slug>/SKILL.md \u2014 will be loaded on next session start.\"\n\n## Reject\n\n1. Call `evolution` with `{ \"action\": \"reject\", \"slug\": \"<slug>\" }` (verifies pending exists, discards it, records the audit entry).\n2. Confirm: \"Rejected <slug>.\"\n\n## Audit\n\nCall `evolution` with `{ \"action\": \"status\" }` and show the audit tail section. If no entries: \"No audit entries.\"\n\n---\n\n# CONSTRAINTS\n\n- Use the `evolution` tool for all state ops \u2014 no bash/rtk for evolution state\n- Never invent slug \u2014 read from the `list` action\n- Keep operations atomic; report errors clearly\n- Do not modify pending content \u2014 promote as-is after human review\n";

package/dist/features/builtin-commands/templates/start-work.d.ts

@@ -1 +1 @@
-export declare const START_WORK_TEMPLATE = "You are starting a Morpheus work session.\n\n## WHAT TO DO\n\n1. **Find available plans**: List Oracle-generated plan files via plan_list at `.matrixx/plans/`\n\n2. **Check for active mission state**: Read `.matrixx/mission.json` if it exists\n\n3. **Decision logic**:\n   - If `.matrixx/mission.json` exists AND plan is NOT complete (has unchecked boxes):\n     - **APPEND** current session to session_ids\n     - Continue work on existing plan\n   - If no active plan OR plan is complete:\n     - List available plan files via plan_list\n     - If ONE plan: auto-select it\n     - If MULTIPLE plans: show list with timestamps, ask user to select\n\n4. **Create/Update mission.json**:\n   ```json\n   {\n     \"active_plan\": \"/absolute/path/to/plan.md\",\n     \"started_at\": \"ISO_TIMESTAMP\",\n     \"session_ids\": [\"session_id_1\", \"session_id_2\"],\n     \"plan_name\": \"plan-name\"\n   }\n   ```\n\n5. **Read the plan file via plan_read** and start executing tasks according to architect workflow\n\n## OUTPUT FORMAT\n\nWhen listing plans for selection:\n```\nAvailable Work Plans\n\nCurrent Time: {ISO timestamp}\nSession ID: {current session id}\n\n1. [plan-name-1.md] - Modified: {date} - Progress: 3/10 tasks\n2. [plan-name-2.md] - Modified: {date} - Progress: 0/5 tasks\n\nWhich plan would you like to work on? (Enter number or plan name)\n```\n\nWhen resuming existing work:\n```\nResuming Work Session\n\nActive Plan: {plan-name}\nProgress: {completed}/{total} tasks\nSessions: {count} (appending current session)\n\nReading plan and continuing from last incomplete task...\n```\n\nWhen auto-selecting single plan:\n```\nStarting Work Session\n\nPlan: {plan-name}\nSession ID: {session_id}\nStarted: {timestamp}\n\nReading plan and beginning execution...\n```\n\n## CRITICAL\n\n- The session_id is injected by the hook - use it directly\n- Always update mission.json BEFORE starting work\n- Read the FULL plan file via plan_read before delegating any tasks\n- Follow architect delegation protocols (7-section format)";
+export declare const START_WORK_TEMPLATE = "You are starting a Morpheus work session.\n\n## WHAT TO DO\n\n1. **Find available plans**: List Oracle-generated plan files via plan_list at `.matrixx/plans/`; each entry carries a progress field (total, completed, remaining, isComplete)\n\n2. **Check for active mission state**: Read `.matrixx/mission.json` if it exists\n\n3. **Decision logic**:\n   - If `.matrixx/mission.json` exists AND plan is NOT complete (has unchecked boxes):\n     - **APPEND** current session to session_ids\n     - Continue work on existing plan\n   - If no active plan OR plan is complete:\n     - List available plan files via plan_list\n     - If ONE plan: auto-select it\n     - If MULTIPLE plans: show list with timestamps, ask user to select\n\n4. **Create/Update mission.json**:\n   ```json\n   {\n     \"active_plan\": \"/absolute/path/to/plan.md\",\n     \"started_at\": \"ISO_TIMESTAMP\",\n     \"session_ids\": [\"session_id_1\", \"session_id_2\"],\n     \"plan_name\": \"plan-name\"\n   }\n   ```\n\n5. **Read the plan**: Call plan_tasks for the task manifest and progress; then read the plan body via paginated plan_read (offset/limit). One call cannot return a plan that renders above the soft cap.\n\n## OUTPUT FORMAT\n\nWhen listing plans for selection:\n```\nAvailable Work Plans\n\nCurrent Time: {ISO timestamp}\nSession ID: {current session id}\n\n1. [plan-name-1.md] - Modified: {date} - Progress: {completed}/{total} tasks\n2. [plan-name-2.md] - Modified: {date} - Progress: {completed}/{total} tasks\n\nWhich plan would you like to work on? (Enter number or plan name)\n```\n\nWhen resuming existing work:\n```\nResuming Work Session\n\nActive Plan: {plan-name}\nProgress: {completed}/{total} tasks\nSessions: {count} (appending current session)\n\nReading plan and continuing from last incomplete task...\n```\n\nWhen auto-selecting single plan:\n```\nStarting Work Session\n\nPlan: {plan-name}\nSession ID: {session_id}\nStarted: {timestamp}\n\nReading plan and beginning execution...\n```\n\n## CRITICAL\n\n- The session_id is injected by the hook - use it directly\n- Always update mission.json BEFORE starting work\n- Call plan_tasks for the manifest; use paginated plan_read (offset/limit) for content \u2014 one call cannot return a plan that renders above the soft cap\n- Follow architect delegation protocols (7-section format)";

package/dist/features/builtin-commands/types.d.ts

@@ -1,3 +1,3 @@
 import type { CommandDefinition } from "../command-loader";
-export type BuiltinCommandName = "init-deep" | "matrix-loop" | "cancel-loop" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "pickup" | "remove-deadcode" | "preset" | "end-ultrawork" | "research" | "assembly" | "ultrawork" | "bdd-backend" | "bdd-contract" | "bdd-frontend" | "bdd-pipeline" | "bdd-tests" | "dcp-profile" | "evolution" | "cleanup-tasks" | "task-list";
+export type BuiltinCommandName = "init-deep" | "matrix-loop" | "cancel-loop" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "pickup" | "remove-deadcode" | "preset" | "end-ultrawork" | "research" | "assembly" | "ultrawork" | "bdd-pipeline" | "evolution" | "cleanup-tasks" | "task-list";
 export type BuiltinCommands = Record<string, CommandDefinition>;

package/dist/features/evolution/compressor/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./interface";
 export * from "./llm";
 import type { EvolutionCompressorConfig } from "../../../config/schema/evolution";
-import type { Compressor } from "./interface";
-export declare function createCompressor(config: EvolutionCompressorConfig, llmCall?: (prompt: string) => Promise<string>): Compressor;
+import type { Compressor, LlmCall } from "./interface";
+export declare function createCompressor(config: EvolutionCompressorConfig, llmCall?: LlmCall): Compressor;

package/dist/features/evolution/compressor/interface.d.ts

@@ -1,5 +1,10 @@
-import type { CompressionInput, DistilledKnowledge } from "../types";
-export interface Compressor {
-    compress(input: CompressionInput): Promise<DistilledKnowledge>;
-}
+import type { CompressionUsage, CompressResult } from "../types";
+export type { Compressor } from "../types";
+export type LlmUsage = CompressionUsage;
+export type LlmResponse = {
+    text: string;
+    usage?: LlmUsage;
+};
+export type LlmCall = (prompt: string, model?: string) => Promise<string | LlmResponse>;
+export type CompressionResult = CompressResult;
 export type { CompressionInput, DistilledKnowledge, TraceRecord } from "../types";

package/dist/features/evolution/compressor/llm.d.ts

@@ -1,12 +1,22 @@
 import type { EvolutionCompressorConfig } from "../../../config/schema/evolution";
-import type { CompressionInput, DistilledKnowledge } from "../types";
-import type { Compressor } from "./interface";
+import { type CompressionInput, type KnowledgeKind, type TraceRecord } from "../types";
+import type { CompressionResult, Compressor, LlmCall } from "./interface";
+/**
+ * Deterministic best-effort kind from trace signals (offline heuristic path).
+ * Rule (pure function of counts + final outcome, no randomness):
+ * - no traces at all → `convention` (nothing to learn from)
+ * - all failed → `gotcha` (warn about the dead end)
+ * - failures present and final trace succeeded → `debugging_pattern` (recovery worth replaying)
+ * - failures present and final trace still failed → `correction` (needs fixes first)
+ * - all succeeded → `workflow` (clean success path)
+ */
+export declare function heuristicKind(traces: TraceRecord[]): KnowledgeKind;
 export declare class LlmCompressor implements Compressor {
     private config;
     private llmCall?;
     constructor(options: {
         config: EvolutionCompressorConfig;
-        llmCall?: (prompt: string) => Promise<string>;
+        llmCall?: LlmCall;
     });
-    compress(input: CompressionInput): Promise<DistilledKnowledge>;
+    compress(input: CompressionInput): Promise<CompressionResult>;
 }

package/dist/features/evolution/evaluator.d.ts

@@ -9,3 +9,13 @@ export declare function evaluateSkill(slug: string, opts?: {
     threshold?: number;
     projectRoot?: string;
 }): Promise<EvalResult>;
+export type EvaluationSweepResult = {
+    evaluated: string[];
+    demoted: string[];
+};
+/** Evaluate every promoted evolution skill (demoting/quarantining low scorers). Safe to call on session idle. */
+export declare function evaluatePromotedSkills(opts?: {
+    threshold?: number;
+    projectRoot?: string;
+    slugs?: string[];
+}): Promise<EvaluationSweepResult>;

package/dist/features/evolution/pipeline.d.ts

@@ -1,7 +1,9 @@
 import type { EvolutionConfig } from "../../config/schema/evolution";
+import type { LlmCall, LlmUsage } from "./compressor/interface";
 import type { CompressionInput } from "./types";
-export declare function runEvolutionPipeline(input: CompressionInput, config: EvolutionConfig): Promise<{
+export declare function runEvolutionPipeline(input: CompressionInput, config: EvolutionConfig, llmCall?: LlmCall): Promise<{
     staged?: string;
     promoted?: string;
     reason?: string;
+    usage?: LlmUsage;
 }>;

package/dist/features/evolution/schema.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { KnowledgeKind } from "./types";
+/**
+ * D5 typed knowledge kinds — DATA schemas (not config knobs).
+ *
+ * The `KnowledgeKind` union lives in `./types` (single source); this module
+ * owns the Zod runtime schema plus the fail-open normalizer used on every
+ * read path (LLM output, stored JSON, legacy meta.json without `kind`).
+ */
+export declare const KNOWLEDGE_KINDS: readonly ["workflow", "correction", "debugging_pattern", "gotcha", "convention"];
+export declare const KnowledgeKindSchema: z.ZodEnum<{
+    workflow: "workflow";
+    correction: "correction";
+    debugging_pattern: "debugging_pattern";
+    gotcha: "gotcha";
+    convention: "convention";
+}>;
+export declare const DEFAULT_KNOWLEDGE_KIND: KnowledgeKind;
+/**
+ * Fail-open normalizer: valid kinds pass through, missing/unknown values
+ * become `convention` instead of throwing (back-compat for stored JSON).
+ */
+export declare function normalizeKnowledgeKind(value: unknown): KnowledgeKind;
+/** Data-shape schema for distilled knowledge (stored/LLM JSON, not config). */
+export declare const DistilledKnowledgeDataSchema: z.ZodObject<{
+    title: z.ZodString;
+    summary: z.ZodString;
+    patterns: z.ZodArray<z.ZodString>;
+    pitfalls: z.ZodArray<z.ZodString>;
+    prerequisites: z.ZodArray<z.ZodString>;
+    skillDraft: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    sourceSessionIDs: z.ZodArray<z.ZodString>;
+    kind: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        workflow: "workflow";
+        correction: "correction";
+        debugging_pattern: "debugging_pattern";
+        gotcha: "gotcha";
+        convention: "convention";
+    }>>>;
+    projectId: z.ZodOptional<z.ZodString>;
+    sourceTraceIDs: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    distilledAt: z.ZodOptional<z.ZodString>;
+    superseded_by: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DistilledKnowledgeData = z.infer<typeof DistilledKnowledgeDataSchema>;

package/dist/features/evolution/store/budget-ledger.d.ts

@@ -0,0 +1,46 @@
+import type { CompressionUsage } from "../types";
+export declare const BUDGET_FILE = ".matrixx/evolution/budget.json";
+/** Typed capacity breach for the writer's pending queue. */
+export declare class MaxPendingError extends Error {
+    readonly pending: number;
+    readonly maxPending: number;
+    constructor(pending: number, maxPending: number);
+}
+/** One recorded compression charge. */
+export type BudgetEvent = {
+    at: string;
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+};
+/** Persisted per-day ledger shape for `.matrixx/evolution/budget.json`. */
+export type BudgetLedger = {
+    day: string;
+    spendCents: number;
+    events: BudgetEvent[];
+};
+/** UTC calendar-day key (`YYYY-MM-DD`) for an instant. Pure. */
+export declare function utcDayKey(at: Date): string;
+/** Absolute ledger path for an evolution dir. */
+export declare function budgetPath(evolutionDir: string): string;
+export declare function emptyLedger(day: string): BudgetLedger;
+/** Reset a ledger when the UTC day rolls over. Pure. */
+export declare function rollLedger(ledger: BudgetLedger, day: string): BudgetLedger;
+/** Include-inclusive cap check for one more charge. Pure. */
+export declare function withinDailyCap(ledger: BudgetLedger, usage: CompressionUsage, maxCostCentsPerDay: number): boolean;
+/** Append a charge to the ledger, rolling the day first. Pure (caller persists). */
+export declare function recordUsage(ledger: BudgetLedger, usage: CompressionUsage, at: Date): BudgetLedger;
+/** True once recorded spend meets or exceeds the daily cap. */
+export declare function isOverDailyCap(ledger: BudgetLedger, maxCostCentsPerDay: number): boolean;
+/** Throw MaxPendingError when the pending queue is full. */
+export declare function checkPendingCapacity(pendingCount: number, maxPending: number): void;
+/** Read the persisted ledger, rolling to `now`'s UTC day; fail-open on any error. */
+export declare function loadLedger(evolutionDir: string, now?: Date): BudgetLedger;
+/** Persist the ledger atomically (tmp + rename), mirroring the repo convention. */
+export declare function saveLedger(evolutionDir: string, ledger: BudgetLedger): void;
+/**
+ * Load-modify-write a charge. Not locked across processes: concurrent writers
+ * follow last-write-wins (a lost charge is acceptable for a single-process
+ * plugin). Sequential callers accumulate correctly.
+ */
+export declare function recordUsageToDisk(evolutionDir: string, usage: CompressionUsage, at?: Date): BudgetLedger;

package/dist/features/evolution/store/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./budget-ledger";
+export * from "./lifecycle";
+export * from "./project-identity";
+export * from "./query";
+export * from "./trace-store";

package/dist/features/evolution/store/lifecycle.d.ts

@@ -0,0 +1,52 @@
+import type { KnowledgeKind } from "../types";
+export declare const QUARANTINE_SEGMENT = "quarantine";
+export type ProposalStatus = "pending" | "approved" | "rejected" | "quarantined" | "superseded";
+export type RetrievalMeta = {
+    status: ProposalStatus;
+    quarantined?: boolean;
+    superseded?: boolean;
+    projectId?: string;
+    kind?: KnowledgeKind;
+    tokenCost?: number;
+};
+export type RetrievalScope = {
+    projectId?: string;
+    kinds?: KnowledgeKind[];
+    tokenCap?: number;
+};
+/**
+ * Normative retrieval contract: approved && !quarantined && !superseded &&
+ * projectScope match && kind match && tokenCap.
+ */
+export declare function isRetrievable(meta: RetrievalMeta, scope: RetrievalScope): boolean;
+export type QuarantineOptions = {
+    projectRoot?: string;
+    sourceDir?: string;
+    reason?: string;
+};
+export type QuarantineResult = {
+    quarantined: boolean;
+    slug: string;
+    quarantinePath: string;
+    reason?: string;
+};
+export declare function promotedDirFor(slug: string, projectRoot?: string): string;
+export declare function quarantineDirFor(slug: string, projectRoot?: string): string;
+/** MOVE a promoted skill under `<evolutionDir>/quarantine/<slug>/` and audit it (instead of rm -rf). */
+export declare function quarantineSkill(slug: string, opts?: QuarantineOptions): Promise<QuarantineResult>;
+/** Restore a previously quarantined skill back to the promoted dir. Owned by T6. */
+export declare function restoreFromQuarantine(slug: string, opts?: {
+    projectRoot?: string;
+    destDir?: string;
+}): Promise<boolean>;
+export type SupersedeOptions = {
+    projectRoot?: string;
+    supersededBy: string;
+};
+export type SupersedeResult = {
+    slug: string;
+    supersededBy: string;
+    superseded: boolean;
+};
+/** Point an old artifact at its live head. Updates meta atomically, audits, never unlinks. */
+export declare function supersedeSkill(slug: string, opts: SupersedeOptions): Promise<SupersedeResult>;

package/dist/features/evolution/store/project-identity.d.ts

@@ -0,0 +1,27 @@
+import { type DistilledKnowledge, UNSCOPED_LEGACY } from "../types";
+export { UNSCOPED_LEGACY };
+export type ProjectIdentity = {
+    projectId: string;
+    root: string;
+    remote?: string;
+};
+/** Injectable git runner: returns trimmed stdout, or null when the command fails. */
+export type GitRunner = (args: string[], cwd: string) => string | null;
+/** Normalize a missing/empty project id to the unscoped sentinel. Pure. */
+export declare function normalizeProjectId(projectId: string | undefined): string;
+/** Lowercase, trim, collapse runs of non-alphanumerics to a single dash. Pure. */
+export declare function normalizeTitle(title: string): string;
+/** Drop the memoized identities (test hook + explicit invalidation). */
+export declare function clearProjectIdentityCache(): void;
+/** Short, stable project suffix used to disambiguate cross-project slugs. Pure. */
+export declare function projectSlugSuffix(projectId: string): string;
+/**
+ * Resolve the git identity for a project root. The id is `sha256:<hex>` of the
+ * git remote URL when one exists, otherwise of the canonical repo-root path.
+ * Results are memoized per canonical root: a second resolve for the same root
+ * spawns no git. `remote` is returned for in-memory use only — callers MUST NOT
+ * persist or log it.
+ */
+export declare function resolveProjectIdentity(root: string, runner?: GitRunner): ProjectIdentity;
+/** Scoped dedup key: projectId + kind + normalized title. Owned by T5. */
+export declare function dedupKey(identity: ProjectIdentity, knowledge: DistilledKnowledge): string;

package/dist/features/evolution/store/query.d.ts

@@ -0,0 +1,23 @@
+import { type RetrievalMeta, type RetrievalScope } from "./lifecycle";
+/** Appended when `get_context` output is cut at the char cap. */
+export declare const CONTEXT_TRUNCATION_MARKER = "\n...[context truncated]";
+/** One read-only retrieval candidate: normalized meta + searchable body. */
+export type RetrievalRecord = {
+    id: string;
+    meta: RetrievalMeta;
+    text: string;
+};
+/**
+ * Enumerate retrieval candidates from the staged skill store and the pending
+ * queue. Staged entries win on slug collisions. Read-only; missing dirs → [].
+ */
+export declare function readRetrievalRecords(projectRoot: string): RetrievalRecord[];
+export type SearchOptions = {
+    /** Case-insensitive substring match against id + body. Absent matches all. */
+    query?: string;
+    scope: RetrievalScope;
+};
+/** Filter records through the T4a predicate, then narrow by text match. */
+export declare function searchRecords(records: RetrievalRecord[], options: SearchOptions): RetrievalRecord[];
+/** Cut text at `cap` chars, appending the marker only when truncation happens. */
+export declare function truncateContext(text: string, cap: number): string;

package/dist/features/evolution/{store.d.ts → store/trace-store.d.ts}

@@ -1,4 +1,4 @@
-import type { EvolutionState, TraceRecord } from "./types";
+import type { EvolutionState, TraceRecord } from "../types";
 export declare const EVOLUTION_DIR = ".matrixx/evolution";
 export declare const TRACES_DIR = ".matrixx/evolution/traces";
 export declare const DISTILLED_DIR = ".matrixx/evolution/distilled";

package/dist/features/evolution/types.d.ts

@@ -12,6 +12,9 @@ export type TraceRecord = {
     errorType?: string;
     model?: string;
 };
+export type KnowledgeKind = "workflow" | "correction" | "debugging_pattern" | "gotcha" | "convention";
+/** Project scope used when git identity is unknown (T4a contract; populated by T5). */
+export declare const UNSCOPED_LEGACY = "unscoped-legacy";
 export type DistilledKnowledge = {
     title: string;
     summary: string;
@@ -21,6 +24,27 @@ export type DistilledKnowledge = {
     skillDraft?: string;
     confidence: number;
     sourceSessionIDs: string[];
+    kind: KnowledgeKind;
+    /** Git-derived project scope; absent normalizes to UNSCOPED_LEGACY. Populated by T5. */
+    projectId?: string;
+    /** Trace ids backing this distillation; absent defaults to []. */
+    sourceTraceIDs: string[];
+    /** ISO timestamp of distillation; absent is back-filled at parse time. */
+    distilledAt: string;
+};
+export type CompressionUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+};
+/**
+ * Cost/usage channel (T4a): `compress()` resolves to `{ knowledge, usage? }` with
+ * `usage = { inputTokens, outputTokens, costCents }`. T1 emits it, T3 (budget-ledger)
+ * consumes it, T8 provenance cites it. No separate store-appended ledger event.
+ */
+export type CompressResult = {
+    knowledge: DistilledKnowledge;
+    usage?: CompressionUsage;
 };
 export type CompressionInput = {
     sessionID: string;
@@ -31,7 +55,7 @@ export type CompressionInput = {
     taskHistory?: unknown[];
 };
 export interface Compressor {
-    compress(input: CompressionInput): Promise<DistilledKnowledge>;
+    compress(input: CompressionInput): Promise<CompressResult>;
 }
 export type EvolutionState = {
     totalTraces: number;
@@ -45,7 +69,16 @@ export type SkillMeta = {
     derived_from: string[];
     created_at: string;
     confidence: number;
+    kind?: KnowledgeKind;
+    /** Git-derived project scope; absent/failing back-compat normalizes to unscoped. */
+    projectId?: string;
     eval_score?: number | null;
     tags?: string[];
     prerequisites?: string[];
+    /** Live-head pointer set on an old artifact when a later re-distill replaces it. */
+    superseded_by?: string;
+    /** Canonical title slug shared across a supersede chain (old + new coexist). */
+    base_slug?: string;
+    /** Content hash used to detect byte-identical re-distills (idempotent suppression). */
+    content_hash?: string;
 };

package/dist/features/evolution/writer-emit.d.ts

@@ -0,0 +1,17 @@
+import type { DistilledKnowledge, KnowledgeKind } from "./types";
+export declare function slugify(title: string): string;
+export type EmitInput = {
+    pendingDir: string;
+    skillsDir: string;
+    slug: string;
+    knowledge: DistilledKnowledge;
+    projectId: string;
+    kind: KnowledgeKind;
+    contentHash: string;
+    baseSlug: string;
+};
+export declare function emitArtifact(input: EmitInput): Promise<{
+    slug: string;
+    pendingPath: string;
+    metaPath: string;
+}>;

package/dist/features/evolution/writer-frontmatter.d.ts

@@ -0,0 +1,23 @@
+import { type KnowledgeKind, type SkillMeta } from "./types";
+/**
+ * Provenance (T8) is the evidence trail behind a generated skill: which
+ * sessions and trace rows it was distilled from, and when. It is emitted both
+ * as SKILL.md YAML frontmatter and mirrored into meta.json.
+ */
+export type ProvenanceMeta = SkillMeta & {
+    session_ids: string[];
+    trace_ids: string[];
+    distilled_at: string;
+};
+export type Provenance = {
+    session_ids: string[];
+    trace_ids: string[];
+    project_id: string;
+    kind: KnowledgeKind;
+    confidence: number;
+    distilled_at: string;
+};
+/** Legacy artifacts predate provenance; loading them must never throw. */
+export declare function hasProvenance(meta: unknown): boolean;
+export declare function provenanceOf(meta: ProvenanceMeta): Provenance;
+export declare function toFrontmatter(meta: ProvenanceMeta): string;

package/dist/features/evolution/writer-supersede.d.ts

@@ -0,0 +1,20 @@
+import type { DistilledKnowledge, KnowledgeKind, SkillMeta } from "./types";
+export type SupersedeKey = {
+    baseSlug: string;
+    projectId: string;
+    kind: KnowledgeKind;
+};
+/** Stable hash of the distillable payload, ignoring volatile timestamps/provenance. */
+export declare function contentHashFor(knowledge: DistilledKnowledge): string;
+/** Distinct, deterministic slug for a chain entry so old and new coexist on disk. */
+export declare function chainSlug(baseSlug: string, contentHash: string): string;
+/** Return `desired`, or the first free `desired-N` when it is already taken. */
+export declare function uniqueSlug(taken: ReadonlySet<string>, desired: string): string;
+/** Read every pending `*.meta.json`; malformed files are skipped, missing dirs yield []. */
+export declare function listPendingMetas(pendingDir: string): SkillMeta[];
+/** Whether a meta shares the (projectId, kind, normalized title) key of a candidate. */
+export declare function knowledgeKeyMatches(meta: SkillMeta, key: SupersedeKey): boolean;
+/** The live artifact for a key: newest matching meta without `superseded_by`. */
+export declare function findLiveHead(metas: SkillMeta[], key: SupersedeKey): SkillMeta | null;
+/** Follow `superseded_by` from `startSlug` to the chain end; fail-open on breaks/cycles. */
+export declare function resolveHeadSlug(metas: SkillMeta[], startSlug: string): string;

package/dist/features/evolution/writer.d.ts

@@ -5,11 +5,15 @@ export declare class EvolutionWriter {
     private skillsDir;
     private promotedBase;
     private globalBase?;
+    private projectRoot;
     constructor(config: EvolutionWriterConfig, projectRoot?: string);
+    private readMeta;
+    private emit;
     stage(knowledge: DistilledKnowledge): Promise<{
         slug: string;
         pendingPath: string;
         metaPath: string;
+        deduped?: boolean;
     }>;
     promote(slug: string): Promise<{
         promotedPath: string;

package/dist/features/knowledge-hub/index.d.ts

@@ -0,0 +1,3 @@
+export type { LoadedHub } from "./loader";
+export { expandHubPath, loadKnowledgeHubs } from "./loader";
+export { resolveKnowledgeFile } from "./resolver";

package/dist/features/knowledge-hub/loader.d.ts

@@ -0,0 +1,11 @@
+import { type KnowledgeConfig, type KnowledgeHub } from "../../config/schema/knowledge";
+export interface LoadedHub {
+    name: string;
+    root: string;
+    indexPath: string;
+    scope: KnowledgeHub["scope"];
+    mode: KnowledgeHub["mode"];
+    exclude: string[];
+}
+export declare function expandHubPath(rawPath: string, projectDir?: string): string;
+export declare function loadKnowledgeHubs(config: KnowledgeConfig | KnowledgeHub[], projectDir?: string): LoadedHub[];

package/dist/features/knowledge-hub/resolver.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedHub } from "./loader";
+export declare function resolveKnowledgeFile(hubs: LoadedHub[], ref: string): string | null;