opencode-matrixx-v2 0.0.0-stage → 1.1.0

package/dist/features/context-injector/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Source identifier for context injection
+ * Each source registers context that will be merged and injected together
+ */
+export type ContextSourceType = "keyword-detector" | "rules-injector" | "directory-agents" | "directory-readme" | "custom";
+/**
+ * Priority levels for context ordering
+ * Higher priority contexts appear first in the merged output
+ */
+export type ContextPriority = "critical" | "high" | "normal" | "low";
+/**
+ * A single context entry registered by a source
+ */
+export interface ContextEntry {
+    /** Unique identifier for this entry within the source */
+    id: string;
+    /** The source that registered this context */
+    source: ContextSourceType;
+    /** The actual context content to inject */
+    content: string;
+    /** Priority for ordering (default: normal) */
+    priority: ContextPriority;
+    /** Timestamp when registered */
+    timestamp: number;
+    /** Optional metadata for debugging/logging */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for registering context
+ */
+export interface RegisterContextOptions {
+    /** Unique ID for this context entry (used for deduplication) */
+    id: string;
+    /** Source identifier */
+    source: ContextSourceType;
+    /** The content to inject */
+    content: string;
+    /** Priority for ordering (default: normal) */
+    priority?: ContextPriority;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of getting pending context for a session
+ */
+export interface PendingContext {
+    /** Merged context string, ready for injection */
+    merged: string;
+    /** Individual entries that were merged */
+    entries: ContextEntry[];
+    /** Whether there's any content to inject */
+    hasContent: boolean;
+}
+/**
+ * Message context from the original user message
+ * Used when injecting to match the message format
+ */
+export interface MessageContext {
+    agent?: string;
+    model?: {
+        providerID?: string;
+        modelID?: string;
+    };
+    path?: {
+        cwd?: string;
+        root?: string;
+    };
+    tools?: Record<string, boolean>;
+}
+/**
+ * Output parts from chat.message hook
+ */
+export interface OutputParts {
+    parts: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Injection strategy
+ */
+export type InjectionStrategy = "prepend-parts" | "storage" | "auto";

package/dist/features/context-mode-routing/routing-block.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared routing block for context-mode guidance.
+ *
+ * Port of upstream `context-mode` `hooks/routing-block.mjs:16-80` (the
+ * `<context_window_protection>` block) plus the Matrixx carve-out sentences
+ * defined in `src/hooks/context-mode-enforcer/constants.ts` (T3) — Read stays
+ * correct for Edit, and shell stays correct for OBSERVE / MUTATE.
+ *
+ * Matrixx ships the context-mode tools under their bare `ctx_*` names, so the
+ * upstream tool-namer indirection collapses to direct references here.
+ */
+export declare const MATRIXX_CONTEXT_MODE_MARKER = "<context_window_protection>";
+/**
+ * Build the full routing block that is injected into the system prompt.
+ * Idempotence is the caller's concern: check for {@link MATRIXX_CONTEXT_MODE_MARKER}
+ * before inserting, using {@link containsContextModeMarker}.
+ */
+export declare function buildContextModeRoutingBlock(): string;
+export declare function buildFallbackRoutingBlock(): string;
+/**
+ * True when the marker is already present in any system message — used for
+ * idempotence so the block is never injected twice into the same prompt.
+ */
+export declare function containsContextModeMarker(system: readonly string[]): boolean;

package/dist/features/context-mode-routing/system-transform.d.ts

@@ -0,0 +1,30 @@
+import type { MatrixxConfig } from "../../config";
+import type { MatrixxContext } from "../../plugin/context";
+import type { Hooks } from "../../plugin/legacy-hooks";
+export declare const HOOK_NAME = "context-mode-routing";
+/** Stable injector id for injection-notifier dedupe. */
+export declare const CONTEXT_MODE_INJECTOR_ID = "context-mode-routing";
+/** Short toast title for the context-mode routing-block injection. */
+export declare const CONTEXT_MODE_NOTICE_TITLE = "Context injection";
+/** Toast message — kept free of keyword-detector triggers (loop-safe). */
+export declare const CONTEXT_MODE_NOTICE_MESSAGE = "Context guidance active";
+type SystemTransformHandler = NonNullable<Hooks["experimental.chat.system.transform"]>;
+/**
+ * Simple FNV-1a string hash (hex) used as the injection-content dedupe key.
+ * Same content → same hash (toast suppressed); changed content → new toast.
+ */
+export declare function hashInjectionContent(content: string): string;
+/**
+ * Builds the `experimental.chat.system.transform` handler that injects the
+ * context-mode routing block into every system prompt.
+ *
+ * Fail-open by design: the hook is guidance, never enforcement, so any error
+ * (malformed output, unexpected SDK shape) returns without throwing and simply
+ * leaves the prompt untouched.
+ *
+ * When `ctx` is provided, a toast is fired via `notifyInjection` exactly once
+ * per session per block version — only after the splice, never on the
+ * marker-present early-return path. Dedupe is handled inside the notifier.
+ */
+export declare function createContextModeSystemTransformHook(pluginConfig: MatrixxConfig, ctx?: MatrixxContext): SystemTransformHandler;
+export {};

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

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

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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,22 @@
+import type { EvolutionCompressorConfig } from "../../../config/schema/evolution";
+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?: LlmCall;
+    });
+    compress(input: CompressionInput): Promise<CompressionResult>;
+}

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

@@ -0,0 +1,11 @@
+import type { SkillMeta } from "./types";
+export declare function containsSecretForEval(text: string): boolean;
+export type EvalResult = {
+    score: number;
+    demoted: boolean;
+};
+export declare function readMeta(slug: string, projectRoot?: string): Promise<SkillMeta | null>;
+export declare function evaluateSkill(slug: string, opts?: {
+    threshold?: number;
+    projectRoot?: string;
+}): Promise<EvalResult>;

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

@@ -0,0 +1,11 @@
+export { createCompressor } from "./compressor";
+export { LlmCompressor } from "./compressor/llm";
+export * from "./evaluator";
+export * from "./pipeline";
+export * from "./store/budget-ledger";
+export * from "./store/lifecycle";
+export * from "./store/project-identity";
+export * from "./store/query";
+export * from "./store/trace-store";
+export * from "./types";
+export * from "./writer";

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

@@ -0,0 +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, 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/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/trace-store.d.ts

@@ -0,0 +1,22 @@
+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";
+export declare const SKILLS_DIR = ".matrixx/evolution/skills";
+export declare const PENDING_DIR = ".matrixx/evolution/pending";
+export declare const STATE_FILE = ".matrixx/evolution/state.json";
+export declare const AUDIT_FILE = ".matrixx/evolution/audit.log";
+export declare class TraceStore {
+    private ringBuffer;
+    private evolutionDir;
+    constructor(evolutionDir?: string);
+    append(record: TraceRecord): Promise<void>;
+    getRecent(count?: number): TraceRecord[];
+    readSession(sessionID: string): Promise<TraceRecord[]>;
+    getAllTraces(sessionID: string): Promise<TraceRecord[]>;
+    cleanup(retentionDays: number): Promise<void>;
+    getState(): Promise<EvolutionState>;
+    updateState(patch: Partial<EvolutionState>): Promise<void>;
+    appendAudit(entry: Record<string, unknown>): Promise<void>;
+}
+export declare const traceStore: TraceStore;

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

@@ -0,0 +1,84 @@
+export type TraceRecord = {
+    id: string;
+    sessionID: string;
+    callID: string;
+    timestamp: string;
+    agent: string;
+    tool: string;
+    args: unknown;
+    output: string;
+    durationMs: number;
+    success: boolean;
+    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;
+    patterns: string[];
+    pitfalls: string[];
+    prerequisites: string[];
+    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;
+    traces: TraceRecord[];
+    messages?: unknown[];
+    notepads?: string[];
+    handoff?: unknown;
+    taskHistory?: unknown[];
+};
+export interface Compressor {
+    compress(input: CompressionInput): Promise<CompressResult>;
+}
+export type EvolutionState = {
+    totalTraces: number;
+    totalCompressions: number;
+    lastCompressionAt?: string;
+    lastPromptAt?: string;
+};
+export type SkillMeta = {
+    name: string;
+    version: string;
+    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

@@ -0,0 +1,24 @@
+import type { EvolutionWriterConfig } from "../../config/schema/evolution";
+import type { DistilledKnowledge } from "./types";
+export declare class EvolutionWriter {
+    private pendingDir;
+    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;
+    }>;
+    reject(slug: string): Promise<void>;
+    listPending(): Promise<string[]>;
+    listPromoted(): Promise<string[]>;
+}

package/dist/features/handoff/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Handoff Storage Constants
+ *
+ * File path constants for the handoff feature. Defined locally to keep the
+ * handoff module self-contained — no dependency on `mission-state/constants`.
+ */
+export declare const HANDOFF_FILE_PATH = ".matrixx/handoff.md";
+export declare const HANDOFF_CONSUMED_FILE_PATH = ".matrixx/handoff.consumed.md";

package/dist/features/handoff/index.d.ts

@@ -0,0 +1,4 @@
+export { HANDOFF_CONSUMED_FILE_PATH, HANDOFF_FILE_PATH, } from "./constants";
+export { type GitHead, GitHeadSchema, type HandoffData, type HandoffDecision, HandoffDecisionSchema, type HandoffFileData, type HandoffFrontmatter, HandoffFrontmatterSchema, type HandoffKeyFile, HandoffKeyFileSchema, HandoffSchema, type HandoffSection, HandoffSectionSchema, } from "./schema";
+export { archiveHandoffFile, ensureHandoffDir, getHandoffConsumedFilePath, getHandoffFilePath, handoffFileExists, readHandoffFile, writeHandoffFile, } from "./storage";
+export { type HandoffValidationResult, validateHandoffYaml, } from "./validate";