opencode-matrixx 2.6.11 → 2.6.13

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/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/plan-contract/appendix.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Plan Contract — Appendix Boundary
+ *
+ * Locates the designated appendix region of a plan. The region begins at the
+ * first H2 whose normalized text is exactly `Appendix` and extends to EOF.
+ * H2s at/after it are exempt from canonical-section and ordering checks.
+ *
+ * Pure content-level helper — accepts a string only, never touches the file system.
+ */
+/**
+ * Return the ZERO-BASED line index of the first `## Appendix` H2, or `-1` when
+ * the plan has no appendix. "Normalized" means the heading text is trimmed.
+ */
+export declare function findAppendixStart(content: string): number;

package/dist/features/plan-contract/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plan Contract Constants
+ *
+ * Canonical structure of an Oracle work plan: the ordered H2 sections and the
+ * required per-task grammar. Checkbox regexes are the single source of truth in
+ * mission-state — re-exported here, never re-declared.
+ */
+export { NUMBERED_CHECKED_RE, NUMBERED_UNCHECKED_RE, TOP_CHECKED_RE, TOP_UNCHECKED_RE, } from "../../features/mission-state/constants";
+/** Ordered H2 section titles, exactly as emitted by the Oracle plan template. */
+export declare const CANONICAL_SECTIONS: readonly ["TL;DR", "Context", "Work Objectives", "Verification Strategy (MANDATORY)", "Execution Strategy", "TODOs", "Commit Strategy", "Success Criteria"];
+/** Ordered labels that every TODO task block must declare. */
+export declare const REQUIRED_TASK_SUBFIELDS: readonly ["What to do", "Must NOT do", "Recommended Agent Profile", "Parallelization", "References", "Acceptance Criteria", "Agent-Executed QA Scenarios"];
+/** Canonical section title union derived from {@link CANONICAL_SECTIONS}. */
+export type PlanSection = (typeof CANONICAL_SECTIONS)[number];
+/** Canonical task subfield label union derived from {@link REQUIRED_TASK_SUBFIELDS}. */
+export type PlanTaskSubfield = (typeof REQUIRED_TASK_SUBFIELDS)[number];

package/dist/features/plan-contract/front-matter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Plan Front-Matter
+ *
+ * Structured YAML front-matter (a leading `---` fenced block) for Oracle plan
+ * files, parsed with `js-yaml`.
+ *
+ * PRECEDENCE: when a front-matter block is present it is authoritative for
+ * `status` and `revision`. The legacy `<!-- plan-persister: {...} -->` comment
+ * (see mission-state `plan-storage.ts`) remains authoritative for `todoTotal`,
+ * `todoCompleted`, `updatedAt` and `sessionId`, and is NEVER removed. Front-matter
+ * is ADDITIVE over that comment, not a replacement.
+ *
+ * Serialization is IDEMPOTENT: `parse(serialize(parse(content)))` equals
+ * `parse(content)`, and `serialize(parse(serialize(fm)))` equals
+ * `serialize(fm)`. On disagreement `status` comes from the front-matter while
+ * the legacy comment is left untouched.
+ */
+import type { PlanFrontMatter } from "./types";
+/**
+ * Parse the leading YAML front-matter block.
+ *
+ * Returns `null` when the block is absent, malformed, or fails the
+ * {@link PlanFrontMatter} shape (e.g. missing `status`/`revision` or an
+ * out-of-vocabulary status).
+ */
+export declare function parsePlanFrontMatter(content: string): PlanFrontMatter | null;
+/**
+ * Serialize front-matter to a `---` fenced YAML block.
+ *
+ * Optional fields are omitted when `undefined`; array fields are emitted even
+ * when empty. The returned block ends with a trailing newline so it can be
+ * prepended to plan content additively.
+ */
+export declare function serializePlanFrontMatter(fm: PlanFrontMatter): string;

package/dist/features/plan-contract/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Plan Contract — barrel
+ *
+ * Foundation module for the plan contract: canonical sections, task grammar,
+ * and the Zod schema for the structured plan view.
+ */
+export { findAppendixStart } from "./appendix";
+export { CANONICAL_SECTIONS, NUMBERED_CHECKED_RE, NUMBERED_UNCHECKED_RE, type PlanSection, type PlanTaskSubfield, REQUIRED_TASK_SUBFIELDS, TOP_CHECKED_RE, TOP_UNCHECKED_RE, } from "./constants";
+export { parsePlanFrontMatter, serializePlanFrontMatter } from "./front-matter";
+export { isGrandfathered, shouldMigrate } from "./migration";
+export { type PlanContract, PlanContractSchema } from "./schema";
+export { renderPlanSkeleton } from "./skeleton";
+export type { PlanContractResult, PlanContractWarning, PlanFrontMatter, PlanStatus, PlanTask, } from "./types";
+export { parsePlanContract, parsePlanTasks, validatePlanContract } from "./validate";

package/dist/features/plan-contract/migration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Plan Front-Matter Migration & Grandfathering
+ *
+ * Front-matter is ADDITIVE over the legacy `<!-- plan-persister: {...} -->`
+ * comment (`mission-state/plan-storage.ts`) — it does not replace it. Migration
+ * is apply-on-next-edit ONLY: no `plan_migrate` tool is shipped and no plan is
+ * rewritten automatically.
+ *
+ * Grandfathering protects the pre-existing plan corpus from retro-breaking: a
+ * plan that lacks front-matter is only exempt when its id is on the frozen
+ * {@link GRANDFATHER_ALLOWLIST}. A brand-new plan lacking front-matter is NOT
+ * grandfathered.
+ */
+/**
+ * Frozen allowlist of plan ids (filename without `.md`) that predate the
+ * front-matter requirement — captured from the live `.matrixx/plans` corpus
+ * (23 files) at planning time.
+ *
+ * Grandfathered plans never emit a front-matter warning and are exempt from any
+ * future FAIL-mode front-matter requirement. The exemption clears as soon as
+ * the plan gains a front-matter block.
+ */
+export declare const GRANDFATHER_ALLOWLIST: readonly string[];
+/**
+ * True IFF the plan has no front-matter AND its id is on the frozen allowlist.
+ *
+ * This is deliberately narrower than "any plan lacking front-matter": a new
+ * non-allowlisted plan returns `false`.
+ */
+export declare function isGrandfathered(filePath: string, content: string): boolean;
+/**
+ * True IFF front-matter is absent, for ANY plan (grandfathered included),
+ * because injection is additive. Idempotent: once front-matter is present this
+ * returns `false`.
+ */
+export declare function shouldMigrate(content: string): boolean;

package/dist/features/plan-contract/schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Plan Contract Schema
+ *
+ * Zod v4 schema for the STRUCTURED view of an Oracle plan. The Markdown grammar
+ * itself is parsed elsewhere; this validates the parsed shape.
+ */
+import { z } from "zod";
+export declare const PlanContractSchema: z.ZodObject<{
+    frontMatter: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            in_progress: "in_progress";
+        }>;
+        revision: z.ZodNumber;
+        phase: z.ZodOptional<z.ZodString>;
+        wave: z.ZodOptional<z.ZodString>;
+        deps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        blockedBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    sections: z.ZodArray<z.ZodString>;
+    tasks: z.ZodArray<z.ZodObject<{
+        n: z.ZodNumber;
+        title: z.ZodString;
+        checked: z.ZodBoolean;
+        line: z.ZodNumber;
+        anchor: z.ZodString;
+    }, z.core.$strip>>;
+    dod: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** Parsed, validated structured view of a plan. */
+export type PlanContract = z.infer<typeof PlanContractSchema>;

package/dist/features/plan-contract/skeleton.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Render the full canonical Oracle plan markdown skeleton — the content between
+ * the `\`\`\`markdown` fences of {@link ORACLE_PLAN_TEMPLATE}.
+ */
+export declare function renderPlanSkeleton(): string;