@personaxis/core 0.11.0

package/dist/sessions.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Conversation sessions — persistent, per-persona chat history (F3).
+ *
+ * The REPL keeps the live conversation in memory and re-sends it each turn; that is
+ * correct for continuity but vanishes on exit. Sessions persist it so a user can leave
+ * and `/resume`, the way Claude Code does. Layout mirrors the rest of the persona's
+ * artifacts and recurses: the root's sessions live in `.personaxis/sessions/`, a sub's in
+ * `.personaxis/personas/<slug>/sessions/`. One append-only `<id>.jsonl` per conversation:
+ * a header line + one line per turn.
+ *
+ * Dependency-free (node:fs only), like memory.ts — sessions are a runtime artifact with
+ * no schema (same status as episodic.jsonl / self-edits.jsonl).
+ */
+import type { ChatMessage } from "./tool-calling.js";
+export type SessionKind = "root" | "sub" | "direct-sub" | "delegation";
+export interface SessionHeader {
+    type: "header";
+    id: string;
+    kind: SessionKind;
+    participants: string[];
+    name: string;
+    created: string;
+    /** Hierarchical address of the owning persona ("" = root) — provenance. */
+    persona: string;
+}
+export interface SessionTurn {
+    type: "turn";
+    /** "note" marks a non-conversational provenance entry (e.g. a delegation record).
+     *  "summary" is a persisted /compact checkpoint: on reload it REPLACES every turn before it
+     *  (which stay in the file for audit) and the verbatim turns after it are kept. */
+    role: "user" | "assistant" | "note" | "summary";
+    content: string;
+    ts: string;
+    /** Who produced an assistant/note turn (address; "(root)" for the root). */
+    from?: string;
+    /** FR.6 threading (Claude Code's transcript shape): this turn's stable id. */
+    uuid?: string;
+    /** FR.6: the uuid this turn replies to — makes branches/regenerations explicit. */
+    parent_uuid?: string;
+}
+export interface SessionSummary {
+    id: string;
+    name: string;
+    kind: SessionKind;
+    created: string;
+    updated: string;
+    turns: number;
+    path: string;
+}
+export declare function sessionsDir(personaPath: string): string;
+/** A filesystem-safe, sortable session id (ISO timestamp + short random suffix). */
+export declare function newSessionId(now?: Date): string;
+/** Create the session file with its header. No-op if it already exists. */
+export declare function ensureSession(personaPath: string, header: Omit<SessionHeader, "type">): void;
+/** Append one turn. Requires the session to already exist (call ensureSession first).
+ * Returns the turn's uuid (generated when not supplied) for parent_uuid threading. */
+export declare function appendTurn(personaPath: string, id: string, turn: {
+    role: SessionTurn["role"];
+    content: string;
+    from?: string;
+    ts?: string;
+    uuid?: string;
+    parentUuid?: string;
+}): string | undefined;
+export declare function readSession(personaPath: string, id: string): {
+    header?: SessionHeader;
+    turns: SessionTurn[];
+};
+/**
+ * Persist a /compact checkpoint. Appends a `summary` turn; on reload it replaces every earlier
+ * turn (kept in the file for audit) so `/resume` returns the COMPACTED conversation, not the raw
+ * bloat. Verbatim turns appended AFTER this checkpoint are preserved until the next compaction.
+ * Best-effort: no-op if the session file doesn't exist yet.
+ */
+export declare function recordCompaction(personaPath: string, id: string, summary: string): void;
+/**
+ * Rehydrate a session into a ChatMessage[] for the agent. Notes are dropped. If a /compact
+ * checkpoint (summary turn) exists, the LAST one replaces everything before it: the rehydrated
+ * conversation is `[<summary as a user message>, ...verbatim turns appended after the checkpoint]`.
+ */
+export declare function loadConversation(personaPath: string, id: string): ChatMessage[];
+/** All sessions for a persona, newest-activity first. */
+export declare function listSessions(personaPath: string): SessionSummary[];
+/** Set a session's display name (rewrites the header line). */
+export declare function renameSession(personaPath: string, id: string, name: string): void;
+/** Resolve a session by exact id, else by case-insensitive name fragment (newest first). */
+export declare function findSession(personaPath: string, query: string): SessionSummary | undefined;
+/** Deterministic fallback title from the first user message. */
+export declare function fallbackName(firstMessage: string): string;
+/** Auto-title a session from its first user message via the LLM (best-effort; may throw). */
+export declare function nameSession(llm: {
+    endpoint: string;
+    model: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}, firstMessage: string): Promise<string>;

package/dist/sessions.js

@@ -0,0 +1,179 @@
+/**
+ * Conversation sessions — persistent, per-persona chat history (F3).
+ *
+ * The REPL keeps the live conversation in memory and re-sends it each turn; that is
+ * correct for continuity but vanishes on exit. Sessions persist it so a user can leave
+ * and `/resume`, the way Claude Code does. Layout mirrors the rest of the persona's
+ * artifacts and recurses: the root's sessions live in `.personaxis/sessions/`, a sub's in
+ * `.personaxis/personas/<slug>/sessions/`. One append-only `<id>.jsonl` per conversation:
+ * a header line + one line per turn.
+ *
+ * Dependency-free (node:fs only), like memory.ts — sessions are a runtime artifact with
+ * no schema (same status as episodic.jsonl / self-edits.jsonl).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+export function sessionsDir(personaPath) {
+    return join(dirname(personaPath), "sessions");
+}
+function sessionFile(personaPath, id) {
+    return join(sessionsDir(personaPath), `${id}.jsonl`);
+}
+/** A filesystem-safe, sortable session id (ISO timestamp + short random suffix). */
+export function newSessionId(now = new Date()) {
+    const ts = now.toISOString().replace(/[:.]/g, "-");
+    const rand = Math.random().toString(36).slice(2, 7);
+    return `${ts}-${rand}`;
+}
+/** Create the session file with its header. No-op if it already exists. */
+export function ensureSession(personaPath, header) {
+    const p = sessionFile(personaPath, header.id);
+    if (existsSync(p))
+        return;
+    mkdirSync(sessionsDir(personaPath), { recursive: true });
+    writeFileSync(p, JSON.stringify({ type: "header", ...header }) + "\n", "utf-8");
+}
+/** Append one turn. Requires the session to already exist (call ensureSession first).
+ * Returns the turn's uuid (generated when not supplied) for parent_uuid threading. */
+export function appendTurn(personaPath, id, turn) {
+    const p = sessionFile(personaPath, id);
+    if (!existsSync(p))
+        return undefined;
+    const uuid = turn.uuid ?? randomUUID();
+    const entry = {
+        type: "turn",
+        ts: turn.ts ?? new Date().toISOString(),
+        role: turn.role,
+        content: turn.content,
+        uuid,
+        ...(turn.parentUuid ? { parent_uuid: turn.parentUuid } : {}),
+        ...(turn.from ? { from: turn.from } : {}),
+    };
+    appendFileSync(p, JSON.stringify(entry) + "\n", "utf-8");
+    return uuid;
+}
+function parseRows(p) {
+    const rows = [];
+    for (const line of readFileSync(p, "utf-8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch {
+            /* skip a corrupt line */
+        }
+    }
+    return rows;
+}
+export function readSession(personaPath, id) {
+    const p = sessionFile(personaPath, id);
+    if (!existsSync(p))
+        return { turns: [] };
+    const rows = parseRows(p);
+    return {
+        header: rows.find((r) => r.type === "header"),
+        turns: rows.filter((r) => r.type === "turn"),
+    };
+}
+/**
+ * Persist a /compact checkpoint. Appends a `summary` turn; on reload it replaces every earlier
+ * turn (kept in the file for audit) so `/resume` returns the COMPACTED conversation, not the raw
+ * bloat. Verbatim turns appended AFTER this checkpoint are preserved until the next compaction.
+ * Best-effort: no-op if the session file doesn't exist yet.
+ */
+export function recordCompaction(personaPath, id, summary) {
+    appendTurn(personaPath, id, { role: "summary", content: summary });
+}
+/**
+ * Rehydrate a session into a ChatMessage[] for the agent. Notes are dropped. If a /compact
+ * checkpoint (summary turn) exists, the LAST one replaces everything before it: the rehydrated
+ * conversation is `[<summary as a user message>, ...verbatim turns appended after the checkpoint]`.
+ */
+export function loadConversation(personaPath, id) {
+    const turns = readSession(personaPath, id).turns;
+    let lastSummary = -1;
+    for (let i = 0; i < turns.length; i++)
+        if (turns[i].role === "summary")
+            lastSummary = i;
+    const out = [];
+    if (lastSummary >= 0) {
+        out.push({ role: "user", content: `<summary of earlier conversation>\n${turns[lastSummary].content}\n</summary>` });
+    }
+    for (let i = lastSummary + 1; i < turns.length; i++) {
+        const t = turns[i];
+        if (t.role === "user" || t.role === "assistant")
+            out.push({ role: t.role, content: t.content });
+    }
+    return out;
+}
+/** All sessions for a persona, newest-activity first. */
+export function listSessions(personaPath) {
+    const dir = sessionsDir(personaPath);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".jsonl"))
+            continue;
+        const id = f.slice(0, -6);
+        const { header, turns } = readSession(personaPath, id);
+        out.push({
+            id,
+            name: header?.name ?? id,
+            kind: header?.kind ?? "root",
+            created: header?.created ?? "",
+            updated: turns.at(-1)?.ts ?? header?.created ?? "",
+            turns: turns.filter((t) => t.role === "user" || t.role === "assistant").length,
+            path: sessionFile(personaPath, id),
+        });
+    }
+    return out.sort((a, b) => b.updated.localeCompare(a.updated));
+}
+/** Set a session's display name (rewrites the header line). */
+export function renameSession(personaPath, id, name) {
+    const p = sessionFile(personaPath, id);
+    if (!existsSync(p))
+        return;
+    const rows = parseRows(p);
+    const header = rows.find((r) => r.type === "header");
+    if (!header)
+        return;
+    header.name = name;
+    writeFileSync(p, rows.map((r) => JSON.stringify(r)).join("\n") + "\n", "utf-8");
+}
+/** Resolve a session by exact id, else by case-insensitive name fragment (newest first). */
+export function findSession(personaPath, query) {
+    const all = listSessions(personaPath);
+    return all.find((s) => s.id === query) ?? all.find((s) => s.name.toLowerCase().includes(query.toLowerCase()));
+}
+/** Deterministic fallback title from the first user message. */
+export function fallbackName(firstMessage) {
+    const words = firstMessage.trim().replace(/\s+/g, " ").split(" ").slice(0, 6).join(" ");
+    return (words || "session").slice(0, 48);
+}
+/** Auto-title a session from its first user message via the LLM (best-effort; may throw). */
+export async function nameSession(llm, firstMessage) {
+    const fetchImpl = llm.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${llm.endpoint.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(llm.apiKey ? { authorization: `Bearer ${llm.apiKey}` } : {}) },
+        body: JSON.stringify({
+            model: llm.model,
+            messages: [
+                { role: "system", content: "You title chat sessions. Reply with ONLY a 2-5 word title in Title Case. No quotes, no trailing punctuation." },
+                { role: "user", content: `First message:\n${firstMessage.slice(0, 400)}` },
+            ],
+            temperature: 0,
+            max_tokens: 16,
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`namer HTTP ${res.status}`);
+    const json = (await res.json());
+    const out = (json.choices?.[0]?.message?.content ?? "").trim().replace(/^["']|["']$/g, "").replace(/[.]+$/, "");
+    if (!out)
+        throw new Error("empty title");
+    return out.slice(0, 60);
+}

package/dist/sigil.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Persona sigil — a deterministic, per-persona visual identity.
+ *
+ * Requirement (plan/09-ascii-ux): showing a persona must be *differentiated per
+ * persona*, never generic. We derive a stable seed from the persona's identity
+ * (canonical_id / display_name) and shape parameters from its quantitative
+ * layers (personality, affect, values), then render a symmetric ASCII glyph plus
+ * a color. The same persona always renders the same sigil; different specs render
+ * visibly different sigils.
+ *
+ * The sigil also "breathes": given the live state.json values (mood/affect) it
+ * shifts density and character set, so a *living* persona looks alive — and looks
+ * alive in a way that is its own, not a shared spinner.
+ *
+ * Pure + dependency-free: returns data; the CLI applies ANSI color.
+ */
+import type { PersonaFrontmatter } from "./persona.js";
+export interface SigilParams {
+    seed: number;
+    /** 0..255 ANSI-256 color index derived from the persona. */
+    color: number;
+    /** Glyph palette (light -> dense) chosen by the seed. */
+    charset: string[];
+    size: number;
+}
+export interface Sigil {
+    params: SigilParams;
+    /** Rows of the rendered glyph (already mirrored / symmetric). */
+    grid: string[];
+}
+export declare function sigilParams(frontmatter: PersonaFrontmatter, size?: number): SigilParams;
+/**
+ * Render a symmetric glyph. `intensity` in [0,1] shifts how dense the glyph is
+ * (driven by live mood/affect for the "breathing" effect).
+ */
+export declare function renderSigil(params: SigilParams, intensity?: number): Sigil;
+/**
+ * Map live state values to a breathing intensity. Higher valence/tone/energy =>
+ * a denser, brighter glyph. Phase animates a subtle pulse over `frame`.
+ */
+export declare function liveIntensity(values: Record<string, number>, frame?: number): number;

package/dist/sigil.js

@@ -0,0 +1,92 @@
+/**
+ * Persona sigil — a deterministic, per-persona visual identity.
+ *
+ * Requirement (plan/09-ascii-ux): showing a persona must be *differentiated per
+ * persona*, never generic. We derive a stable seed from the persona's identity
+ * (canonical_id / display_name) and shape parameters from its quantitative
+ * layers (personality, affect, values), then render a symmetric ASCII glyph plus
+ * a color. The same persona always renders the same sigil; different specs render
+ * visibly different sigils.
+ *
+ * The sigil also "breathes": given the live state.json values (mood/affect) it
+ * shifts density and character set, so a *living* persona looks alive — and looks
+ * alive in a way that is its own, not a shared spinner.
+ *
+ * Pure + dependency-free: returns data; the CLI applies ANSI color.
+ */
+import { createHash } from "node:crypto";
+const CHARSETS = [
+    [" ", "·", ":", "*", "✦", "█"],
+    [" ", ".", "+", "x", "#", "█"],
+    [" ", "˙", "∘", "○", "◍", "●"],
+    [" ", "·", "✶", "✷", "✸", "✹"],
+    [" ", "░", "▒", "▓", "█", "█"],
+    [" ", "⋄", "◇", "◈", "◆", "▰"],
+];
+function seedFrom(frontmatter) {
+    const id = frontmatter.identity;
+    const meta = frontmatter.metadata;
+    const key = id?.canonical_id ?? id?.display_name ?? meta?.name ?? "persona";
+    const hex = createHash("sha256").update(String(key)).digest("hex").slice(0, 8);
+    return parseInt(hex, 16) >>> 0;
+}
+/** A tiny xorshift PRNG so the whole sigil is reproducible from one seed. */
+function rng(seed) {
+    let s = seed || 0x9e3779b9;
+    return () => {
+        s ^= s << 13;
+        s ^= s >>> 17;
+        s ^= s << 5;
+        s >>>= 0;
+        return s / 0xffffffff;
+    };
+}
+export function sigilParams(frontmatter, size = 7) {
+    const seed = seedFrom(frontmatter);
+    return {
+        seed,
+        color: 17 + (seed % 214), // skip the dim 0-16 range
+        charset: CHARSETS[seed % CHARSETS.length],
+        size: size % 2 === 0 ? size + 1 : size,
+    };
+}
+/**
+ * Render a symmetric glyph. `intensity` in [0,1] shifts how dense the glyph is
+ * (driven by live mood/affect for the "breathing" effect).
+ */
+export function renderSigil(params, intensity = 0.5) {
+    const { size, charset } = params;
+    const half = Math.ceil(size / 2);
+    const next = rng(params.seed);
+    const rows = [];
+    const density = 0.25 + intensity * 0.6;
+    for (let y = 0; y < size; y++) {
+        let left = "";
+        for (let x = 0; x < half; x++) {
+            const r = next();
+            // radial falloff so the glyph reads as a centered sigil
+            const cy = (y - (size - 1) / 2) / size;
+            const cx = (x - (size - 1) / 2) / size;
+            const radial = 1 - Math.min(1, Math.sqrt(cx * cx + cy * cy) * 1.4);
+            const v = r * (0.5 + radial) * density;
+            const idx = Math.max(0, Math.min(charset.length - 1, Math.floor(v * charset.length)));
+            left += charset[idx];
+        }
+        const mid = size % 2 === 1 ? left[left.length - 1] : "";
+        const right = left.slice(0, size - half).split("").reverse().join("");
+        rows.push((left + (mid ? "" : "") + right).slice(0, size));
+    }
+    return { params, grid: rows };
+}
+/**
+ * Map live state values to a breathing intensity. Higher valence/tone/energy =>
+ * a denser, brighter glyph. Phase animates a subtle pulse over `frame`.
+ */
+export function liveIntensity(values, frame = 0) {
+    const tone = values["mood.tone"] ?? 0;
+    const valence = values["affect.valence"] ?? 0;
+    const arousal = values["affect.arousal"] ?? values["mood.energy"] ?? 0;
+    const base = 0.5 + (tone + valence) * 0.25 + arousal * 0.1;
+    const pulse = Math.sin(frame / 2) * 0.08 * (0.5 + arousal);
+    return Math.max(0.05, Math.min(1, base + pulse));
+}

package/dist/skill-lifecycle.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Skill lifecycle governance (F6 — plan/06-skills; SkillsVote, Liu et al., 2026).
+ *
+ * We don't author skills; we use them from external sources. Beyond the pre-use
+ * security review (skill-review.ts), a skill must be *governed over its life*:
+ *   - attribution: record each use + outcome (success/failure) -> success rate;
+ *   - recommendation: rank candidates by security verdict, success rate, and
+ *     capability match — never recommend an unreviewed/dangerous skill;
+ *   - evolution: evidence-gated — a new version is promoted ONLY if it beats the
+ *     incumbent on success rate over a minimum sample (revert-on-regression);
+ *     persistently failing skills are deprecated.
+ *
+ * Append-only JSONL ledger (auditable, never rewritten), folded for current state.
+ */
+export type SkillOp = "register" | "use" | "outcome" | "promote" | "deprecate";
+export interface SkillEvent {
+    ts: string;
+    skill: string;
+    version: string;
+    op: SkillOp;
+    outcome?: "success" | "failure";
+    note?: string;
+}
+export interface SkillStats {
+    skill: string;
+    version: string;
+    uses: number;
+    successes: number;
+    failures: number;
+    successRate: number;
+    status: "active" | "deprecated";
+}
+export interface SkillCandidate {
+    skill: string;
+    version: string;
+    capabilities: string[];
+    /** Verdict from reviewSkill(): ok | review | danger. */
+    reviewVerdict: "ok" | "review" | "danger";
+}
+export interface Recommendation {
+    skill: string;
+    version: string;
+    score: number;
+    reasons: string[];
+}
+export declare class SkillLedger {
+    private file;
+    constructor(baseDir: string);
+    private append;
+    events(): SkillEvent[];
+    register(skill: string, version: string): void;
+    recordUse(skill: string, version: string): void;
+    recordOutcome(skill: string, version: string, success: boolean, note?: string): void;
+    deprecate(skill: string, version: string, note?: string): void;
+    promote(skill: string, version: string, note?: string): void;
+    stats(skill: string, version: string): SkillStats;
+    /**
+     * Evidence-gated evolution. Promote `to` over `from` only if `to` has at least
+     * `minSample` outcomes AND its success rate beats `from` by `margin`. Otherwise
+     * keep the incumbent (revert-on-regression). Returns the decision.
+     */
+    evolve(skill: string, from: string, to: string, opts?: {
+        minSample?: number;
+        margin?: number;
+    }): {
+        promoted: boolean;
+        reason: string;
+    };
+    /**
+     * Recommend skills for a task. Dangerous skills are excluded; the rest are ranked
+     * by capability match × trust(review) × (0.5 + successRate).
+     */
+    recommend(candidates: SkillCandidate[], taskTokens: string[]): Recommendation[];
+}

package/dist/skill-lifecycle.js

@@ -0,0 +1,126 @@
+/**
+ * Skill lifecycle governance (F6 — plan/06-skills; SkillsVote, Liu et al., 2026).
+ *
+ * We don't author skills; we use them from external sources. Beyond the pre-use
+ * security review (skill-review.ts), a skill must be *governed over its life*:
+ *   - attribution: record each use + outcome (success/failure) -> success rate;
+ *   - recommendation: rank candidates by security verdict, success rate, and
+ *     capability match — never recommend an unreviewed/dangerous skill;
+ *   - evolution: evidence-gated — a new version is promoted ONLY if it beats the
+ *     incumbent on success rate over a minimum sample (revert-on-regression);
+ *     persistently failing skills are deprecated.
+ *
+ * Append-only JSONL ledger (auditable, never rewritten), folded for current state.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export class SkillLedger {
+    file;
+    constructor(baseDir) {
+        this.file = join(baseDir, "skills-ledger.jsonl");
+    }
+    append(e) {
+        mkdirSync(dirname(this.file), { recursive: true });
+        appendFileSync(this.file, JSON.stringify(e) + "\n", "utf-8");
+    }
+    events() {
+        if (!existsSync(this.file))
+            return [];
+        return readFileSync(this.file, "utf-8")
+            .split("\n")
+            .filter((l) => l.trim())
+            .map((l) => JSON.parse(l));
+    }
+    register(skill, version) {
+        this.append({ ts: new Date().toISOString(), skill, version, op: "register" });
+    }
+    recordUse(skill, version) {
+        this.append({ ts: new Date().toISOString(), skill, version, op: "use" });
+    }
+    recordOutcome(skill, version, success, note) {
+        this.append({ ts: new Date().toISOString(), skill, version, op: "outcome", outcome: success ? "success" : "failure", note });
+    }
+    deprecate(skill, version, note) {
+        this.append({ ts: new Date().toISOString(), skill, version, op: "deprecate", note });
+    }
+    promote(skill, version, note) {
+        this.append({ ts: new Date().toISOString(), skill, version, op: "promote", note });
+    }
+    stats(skill, version) {
+        let uses = 0, successes = 0, failures = 0, deprecated = false;
+        for (const e of this.events()) {
+            if (e.skill !== skill || e.version !== version)
+                continue;
+            if (e.op === "use")
+                uses++;
+            else if (e.op === "outcome") {
+                if (e.outcome === "success")
+                    successes++;
+                else
+                    failures++;
+            }
+            else if (e.op === "deprecate")
+                deprecated = true;
+            else if (e.op === "promote")
+                deprecated = false;
+        }
+        const total = successes + failures;
+        return {
+            skill,
+            version,
+            uses,
+            successes,
+            failures,
+            successRate: total === 0 ? 0 : Number((successes / total).toFixed(3)),
+            status: deprecated ? "deprecated" : "active",
+        };
+    }
+    /**
+     * Evidence-gated evolution. Promote `to` over `from` only if `to` has at least
+     * `minSample` outcomes AND its success rate beats `from` by `margin`. Otherwise
+     * keep the incumbent (revert-on-regression). Returns the decision.
+     */
+    evolve(skill, from, to, opts = {}) {
+        const minSample = opts.minSample ?? 5;
+        const margin = opts.margin ?? 0.02;
+        const a = this.stats(skill, from);
+        const b = this.stats(skill, to);
+        const bTotal = b.successes + b.failures;
+        if (bTotal < minSample) {
+            return { promoted: false, reason: `candidate has ${bTotal} outcomes (< minSample ${minSample})` };
+        }
+        if (b.successRate >= a.successRate + margin) {
+            this.promote(skill, to, `beats ${from} (${b.successRate} >= ${a.successRate}+${margin})`);
+            this.deprecate(skill, from, `superseded by ${to}`);
+            return { promoted: true, reason: `${to} promoted over ${from}` };
+        }
+        return { promoted: false, reason: `${to} (${b.successRate}) does not beat ${from} (${a.successRate}) by ${margin}` };
+    }
+    /**
+     * Recommend skills for a task. Dangerous skills are excluded; the rest are ranked
+     * by capability match × trust(review) × (0.5 + successRate).
+     */
+    recommend(candidates, taskTokens) {
+        const recs = [];
+        for (const c of candidates) {
+            const reasons = [];
+            if (c.reviewVerdict === "danger") {
+                continue; // never recommend a dangerous skill
+            }
+            const st = this.stats(c.skill, c.version);
+            if (st.status === "deprecated")
+                continue;
+            const caps = new Set(c.capabilities);
+            const matched = taskTokens.filter((t) => caps.has(t));
+            const matchScore = taskTokens.length ? matched.length / taskTokens.length : 0;
+            const trust = c.reviewVerdict === "ok" ? 1 : 0.6;
+            const score = Number((matchScore * trust * (0.5 + st.successRate)).toFixed(3));
+            if (matched.length > 0)
+                reasons.push(`matched: ${matched.join(", ")}`);
+            reasons.push(`review: ${c.reviewVerdict}`, `successRate: ${st.successRate}`);
+            if (score > 0)
+                recs.push({ skill: c.skill, version: c.version, score, reasons });
+        }
+        return recs.sort((a, b) => b.score - a.score);
+    }
+}

package/dist/skill-review.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Skill security review (F6 — plan/06-skills).
+ *
+ * We don't maintain skills; we USE them from external sources (Anthropic, GitHub,
+ * ClawHub). But ~26% of community skills carry vulnerabilities (Xu & Yan, 2026)
+ * and the ClawHavoc campaign shipped 1,200+ malicious skills. So every skill is
+ * scanned BEFORE use: risky shell/network/eval/secret patterns are flagged, a
+ * verdict is produced, and a content hash is returned for allowlisting. Never
+ * auto-update; pin by hash.
+ */
+export type Severity = "info" | "warn" | "danger";
+export interface SkillFinding {
+    severity: Severity;
+    rule: string;
+    file: string;
+    match: string;
+}
+export interface SkillReview {
+    skillPath: string;
+    files: string[];
+    hash: string;
+    findings: SkillFinding[];
+    verdict: "ok" | "review" | "danger";
+}
+export declare function reviewSkill(skillPath: string): SkillReview;