dsh-continual-evolve 0.3.0 → 0.4.0

package/lib/fate.js

@@ -1,4 +1,5 @@
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { DEFAULT_PROMOTION_POLICY } from "./promotion.js";
 import { questionServiceOf } from "./approval.js";
 import { assessLocalEntries, candidateKey, filterPromotable, listLocalCandidates, splitArchiveGuards, splitPromoteBlocked, splitPromoteProposals, wholePromoteProposals, } from "./wrapup.js";
 /** Turns a declined local-fate proposal stays silent before being offered again. */
@@ -9,9 +10,9 @@ export const FATE_CONSULT_COOLDOWN_TURNS = 10;
  * may have changed while the LLM call was in flight). Pure and unit-tested;
  * mirrors the partition step of the wrap-up command.
  */
-export function planLocalFates(items, candidates, globalState) {
+export function planLocalFates(items, candidates, globalState, policy = DEFAULT_PROMOTION_POLICY) {
     const byKey = new Map(candidates.map((candidate) => [candidateKey(candidate.kind, candidate.id), candidate]));
-    const { promotable, skipped } = filterPromotable(items, globalState, candidates);
+    const { promotable, skipped } = filterPromotable(items, globalState, candidates, policy);
     const promoteItems = promotable.filter((item) => item.verdict === "promote");
     const archiveItems = items.filter((item) => item.verdict === "archive");
     const splits = [];
@@ -24,7 +25,7 @@ export function planLocalFates(items, candidates, globalState) {
             splitSkipped.push({ key: item.key, reason: "not in the audited candidate list" });
             continue;
         }
-        const blocked = splitPromoteBlocked(item, globalState, candidate.kind);
+        const blocked = splitPromoteBlocked(item, globalState, candidate.kind, policy);
         if (blocked) {
             splitSkipped.push({ key: item.key, reason: blocked });
             continue;
@@ -230,7 +231,7 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
         });
         return;
     }
-    const plan = planLocalFates(assessment.items, candidates, globalState);
+    const plan = planLocalFates(assessment.items, candidates, globalState, config.promotionPolicy);
     const needsDialog = plan.promotable.length + plan.splits.length + plan.reviewArchives.length > 0;
     let consent = { approved: false, asked: false, reason: "nothing-to-ask" };
     if (reason !== "compact" && needsDialog) {

package/lib/index.d.ts

@@ -57,6 +57,17 @@ export declare const Config: z<Schemastery.ObjectS<{
      * assessment so the encounter is distilled. 0 disables.
      */
     goalBlockedWrapupTurns: z<number, number>;
+    /**
+     * Promotion policy (2026-08-22): regex sources whose match in a
+     * candidate's title/content marks it project-scoped — such entries are
+     * never promoted to the cross-session global store. Replaces the built-in
+     * defaults when set.
+     */
+    promotionBlockPatterns: z<string[], string[]>;
+    /** Whole promotions below this content length stay local (chars). */
+    promotionMinChars: z<number, number>;
+    /** Entry-directory lines injected per build before folding into a counter. */
+    injectionDirectoryLines: z<number, number>;
 }>, Schemastery.ObjectT<{
     /** Root for evolution stores; defaults to the resolved DSH home. */
     baseDir: z<string, string>;
@@ -109,6 +120,17 @@ export declare const Config: z<Schemastery.ObjectS<{
      * assessment so the encounter is distilled. 0 disables.
      */
     goalBlockedWrapupTurns: z<number, number>;
+    /**
+     * Promotion policy (2026-08-22): regex sources whose match in a
+     * candidate's title/content marks it project-scoped — such entries are
+     * never promoted to the cross-session global store. Replaces the built-in
+     * defaults when set.
+     */
+    promotionBlockPatterns: z<string[], string[]>;
+    /** Whole promotions below this content length stay local (chars). */
+    promotionMinChars: z<number, number>;
+    /** Entry-directory lines injected per build before folding into a counter. */
+    injectionDirectoryLines: z<number, number>;
 }>>;
 /**
  * Structurally typed resolved config (loader passes the validated object).

package/lib/index.js

@@ -19,6 +19,7 @@ import { entriesSectionText } from "./inject.js";
 import { resolveRubricKey } from "./rubric.js";
 import { restoreMounted } from "./mount.js";
 import { registerFileLogger } from "./logfile.js";
+import { resolvePromotionPolicy } from "./promotion.js";
 export const name = "continual-evolve";
 /** Service key under which the evolution engine is published. */
 export const EVOLUTION_SERVICE = "evolution";
@@ -75,6 +76,17 @@ export const Config = z.object({
      * assessment so the encounter is distilled. 0 disables.
      */
     goalBlockedWrapupTurns: z.natural().min(0).default(3),
+    /**
+     * Promotion policy (2026-08-22): regex sources whose match in a
+     * candidate's title/content marks it project-scoped — such entries are
+     * never promoted to the cross-session global store. Replaces the built-in
+     * defaults when set.
+     */
+    promotionBlockPatterns: z.array(z.string()),
+    /** Whole promotions below this content length stay local (chars). */
+    promotionMinChars: z.natural().default(100),
+    /** Entry-directory lines injected per build before folding into a counter. */
+    injectionDirectoryLines: z.natural().default(15),
 });
 export function apply(ctx, config) {
     const baseDir = resolveDshHome(config.baseDir);
@@ -107,13 +119,18 @@ export function apply(ctx, config) {
     ctx.systemPrompt.section({
         name: "tool:continual-evolve:entries",
         order: (config.sectionOrder ?? 118) + 1,
-        text: (context) => entriesSectionText(engine, context.agent),
+        text: (context) => entriesSectionText(engine, context.agent, undefined, { directoryLines: config.injectionDirectoryLines ?? 15 }),
     });
     const gate = { requireGlobalApproval: config.requireGlobalApproval ?? true };
+    const promotionPolicy = resolvePromotionPolicy({
+        blockPatterns: config.promotionBlockPatterns,
+        minPromoteChars: config.promotionMinChars,
+    });
     registerEvolveTools(ctx, engine, gate);
     registerEvolveCommand(ctx, engine, gate, {
         rubricKey: resolveRubricKey(baseDir, config.rubricKey, process.env, (m) => ctx.logger("continual-evolve").warn(m)),
         autoRollbackOnReject: config.autoRollbackOnReject ?? true,
+        promotionPolicy,
     });
     // Plugin-owned file logging: every cordis log message lands in
     // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
@@ -137,6 +154,7 @@ export function apply(ctx, config) {
             localFate: config.localFate ?? true,
             fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
             goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
+            promotionPolicy,
             ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
         });
         ctx.logger("continual-evolve").info(`continual-evolve auto-review enabled (every ${config.reviewIntervalTurns ?? 6} turns; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);

package/lib/inject.d.ts

@@ -109,8 +109,16 @@ export declare function formatSubagentSpecsSection(entries: readonly HarnessEntr
  * the model a zero-cost overview of what exists so it can ask for full text
  * via `evolve_list` or `/evolve list`. The directory is appended after the
  * curated top-N injection sections and adds minimal tokens.
+ *
+ * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
+ * lines (oldest-sorted stable order) with the remainder folded into a single
+ * counter line — an uncapped directory across a polluted global store was
+ * measured at ~2K chars of every build in every project.
  */
+export declare const DEFAULT_DIRECTORY_LINES = 15;
 export declare function formatEntriesDirectory(...kindEntries: readonly HarnessEntry[][]): string;
+/** {@link formatEntriesDirectory} with an explicit cap (configurable). */
+export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEntries: readonly HarnessEntry[][]): string;
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
  * session whose local store is non-empty, if any. Children inherit their
@@ -127,6 +135,13 @@ export declare function nearestLocalStateWithEntries(engine: EvolutionEngine, ag
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
+ *
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * Usage recording covers ALL kinds — memories and skills appear as directory
+ * lines, prompts/subagents as content — and is deduped per session so the
+ * counts read "how many sessions saw this", not "how many prompt builds".
  */
-export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string): string;
+export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string, opts?: {
+    directoryLines?: number;
+}): string;
 //# sourceMappingURL=inject.d.ts.map

package/lib/inject.js

@@ -190,22 +190,45 @@ export function formatSubagentSpecsSection(entries, query) {
  * the model a zero-cost overview of what exists so it can ask for full text
  * via `evolve_list` or `/evolve list`. The directory is appended after the
  * curated top-N injection sections and adds minimal tokens.
+ *
+ * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
+ * lines (oldest-sorted stable order) with the remainder folded into a single
+ * counter line — an uncapped directory across a polluted global store was
+ * measured at ~2K chars of every build in every project.
  */
+export const DEFAULT_DIRECTORY_LINES = 15;
+/** How many of the variadic arrays are content-section kinds (prompt, subagent). */
+const CONTENT_SECTION_KINDS = 2;
 export function formatEntriesDirectory(...kindEntries) {
+    return formatEntriesDirectoryCapped(DEFAULT_DIRECTORY_LINES, ...kindEntries);
+}
+/** {@link formatEntriesDirectory} with an explicit cap (configurable). */
+export function formatEntriesDirectoryCapped(maxLines, ...kindEntries) {
     const allEntries = kindEntries.flat().filter((e) => !isArchived(e));
     if (allEntries.length === 0) {
         return "";
     }
-    // Skip the directory when it would be redundant (all entries already shown
-    // in the curated sections above — 6/kind cap means ≤6 entries total).
-    const totalCapped = kindEntries.reduce((sum, entries) => sum + Math.min(entries.filter((e) => !isArchived(e)).length, MAX_INJECTED_ENTRIES_PER_KIND), 0);
-    if (allEntries.length <= totalCapped) {
+    // Skip the directory only when EVERY entry is already content-visible.
+    // Only the first two arrays (prompt, subagent) have curated sections —
+    // memories and skills have NO content injection, so they are invisible
+    // unless the directory lists them (pre-2026-08-22 the redundancy check
+    // wrongly counted them as "already shown", hiding small stores entirely).
+    const contentVisible = kindEntries
+        .slice(0, CONTENT_SECTION_KINDS)
+        .reduce((sum, entries) => sum + Math.min(entries.filter((e) => !isArchived(e)).length, MAX_INJECTED_ENTRIES_PER_KIND), 0);
+    if (allEntries.length <= contentVisible) {
         return "";
     }
+    const sorted = [...allEntries].sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
     const lines = ["# Continual Harness — Entry Directory", "All entries (use evolve_list for full text of any entry):"];
-    for (const entry of allEntries.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`))) {
+    const shown = sorted.slice(0, Math.max(maxLines, 1));
+    for (const entry of shown) {
         lines.push(`- [${entry.kind}:${entry.id}] ${entry.title}`);
     }
+    const hidden = sorted.length - shown.length;
+    if (hidden > 0) {
+        lines.push(`- …and ${hidden} more entries (evolve_list for the full index)`);
+    }
     return lines.join("\n");
 }
 /**
@@ -236,8 +259,13 @@ export function nearestLocalStateWithEntries(engine, agent) {
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
+ *
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * Usage recording covers ALL kinds — memories and skills appear as directory
+ * lines, prompts/subagents as content — and is deduped per session so the
+ * counts read "how many sessions saw this", not "how many prompt builds".
  */
-export function entriesSectionText(engine, agent, query) {
+export function entriesSectionText(engine, agent, query, opts) {
     if (!agent) {
         return "";
     }
@@ -250,28 +278,41 @@ export function entriesSectionText(engine, agent, query) {
     // Build injected text and collect which entries were included (gap B1).
     const promptText = formatPromptEntriesSection(promptEntries, relevanceQuery);
     const subagentText = formatSubagentSpecsSection(subagentEntries, relevanceQuery);
-    const injectedKeys = [];
+    const injectedKeys = new Set();
     // Collect keys from the visible (ranked, capped) entries that actually appear.
     const visiblePrompt = promptEntries.filter((e) => !isArchived(e));
     const visibleSubagent = subagentEntries.filter((e) => !isArchived(e));
     for (const entry of rankEntries(visiblePrompt, relevanceQuery).slice(0, MAX_INJECTED_ENTRIES_PER_KIND)) {
-        injectedKeys.push(`prompt:${entry.id}`);
+        injectedKeys.add(`prompt:${entry.id}`);
     }
     for (const entry of rankEntries(visibleSubagent, relevanceQuery).slice(0, MAX_INJECTED_ENTRIES_PER_KIND)) {
-        injectedKeys.push(`subagent:${entry.id}`);
+        injectedKeys.add(`subagent:${entry.id}`);
+    }
+    // Gap B3: lightweight directory of ALL entries (id+title, one line each).
+    // Zero-cost index so the model knows what exists and can ask for full text.
+    const directoryText = formatEntriesDirectoryCapped(opts?.directoryLines ?? DEFAULT_DIRECTORY_LINES, Object.values(merged.entries.prompt), Object.values(merged.entries.memory), Object.values(merged.entries.skill), Object.values(merged.entries.subagent));
+    // Directory-visible keys count too: a memory's injection IS its directory
+    // line. Set semantics keep content-injected entries single-counted.
+    for (const kind of ["prompt", "memory", "skill", "subagent"]) {
+        for (const entry of Object.values(merged.entries[kind])) {
+            if (isArchived(entry))
+                continue;
+            const key = `${kind}:${entry.id}`;
+            if (injectedKeys.has(key) || directoryText.includes(`[${key}]`)) {
+                injectedKeys.add(key);
+            }
+        }
     }
     // Record usage durably (best-effort: failure never blocks injection).
-    if (injectedKeys.length > 0) {
+    // Deduped per session — see recordInjection.
+    if (injectedKeys.size > 0) {
         try {
-            recordInjection(engine.baseDir, injectedKeys);
+            recordInjection(engine.baseDir, [...injectedKeys], agent.id);
         }
         catch {
             // Usage recording is diagnostic; never interrupt the injection path.
         }
     }
-    // Gap B3: lightweight directory of ALL entries (id+title, one line each).
-    // Zero-cost index so the model knows what exists and can ask for full text.
-    const directoryText = formatEntriesDirectory(Object.values(merged.entries.prompt), Object.values(merged.entries.memory), Object.values(merged.entries.skill), Object.values(merged.entries.subagent));
     const parts = [promptText, subagentText, directoryText].filter((part) => part.length > 0);
     return parts.join("\n\n");
 }

package/lib/promotion.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Promotion policy: mechanical, code-enforced gates that decide whether a
+ * local entry MAY be promoted to the cross-session global store ("模型提议，
+ * 代码保证"). The LLM classification proposes; these guards dispose.
+ *
+ * Rationale (2026-08-22 store audit): the global store is shared by every
+ * project on one profile, so promoting project-scoped knowledge taxes every
+ * future session in every project. Measured failure modes:
+ * - absolute paths / session ids in promoted content (project-scoped),
+ * - near-duplicates of existing global entries re-promoted from later
+ *   sessions (title matching alone missed them),
+ * - one-line facts whose framing costs more than their content.
+ *
+ * Pure functions only — the callers (wrapup command, gate local-fate phase)
+ * supply the resolved {@link PromotionPolicy}.
+ */
+import type { HarnessState, RefinementKind } from "./types.js";
+export interface PromotionPolicy {
+    /** Content matching any pattern is project-scoped and stays local. */
+    blockPatterns: RegExp[];
+    /** Whole promotions below this content length stay local (chars). */
+    minPromoteChars: number;
+    /** Content overlap above this against a global entry = duplicate. */
+    maxContentOverlap: number;
+}
+export declare const DEFAULT_PROMOTION_POLICY: PromotionPolicy;
+/**
+ * Build a policy from config values (schemastery strings compiled here so
+ * the config layer never touches RegExp). Invalid patterns are skipped —
+ * a broken user pattern must not disable the remaining guards.
+ */
+export declare function resolvePromotionPolicy(options: {
+    blockPatterns?: readonly string[] | undefined;
+    minPromoteChars?: number | undefined;
+    maxContentOverlap?: number | undefined;
+}): PromotionPolicy;
+/**
+ * First reason the content reads as project-scoped, or undefined when it
+ * looks portable. Returns the matched pattern source so skip reports stay
+ * explainable in reviews.jsonl rationales.
+ */
+export declare function projectScopedReason(content: string, policy: PromotionPolicy): string | undefined;
+/**
+ * Tokenize for cheap similarity: ASCII words plus CJK character bigrams
+ * (single CJK chars are too ambiguous; bigrams survive segmentation-free
+ * Chinese text). Lowercased; single-char ASCII tokens dropped as noise.
+ */
+export declare function normalizedTokens(text: string): Set<string>;
+/** Jaccard similarity of two texts' normalized token sets (0..1). */
+export declare function contentOverlap(a: string, b: string): number;
+export interface SimilarEntryHit {
+    id: string;
+    title: string;
+    score: number;
+}
+/**
+ * The most similar non-archived global entry of the same kind, above the
+ * policy threshold. Title and content both feed the comparison (titles are
+ * short; content carries the real signal).
+ */
+export declare function mostSimilarGlobalEntry(globalState: HarnessState, kind: RefinementKind, title: string, content: string, policy: PromotionPolicy): SimilarEntryHit | undefined;
+//# sourceMappingURL=promotion.d.ts.map

package/lib/promotion.js

@@ -0,0 +1,102 @@
+import { isArchived } from "./types.js";
+/** Regex sources that mark content as project-scoped (never global). */
+const DEFAULT_BLOCK_PATTERNS = [
+    String.raw `\/(?:mnt|home|Users)\/`, // absolute POSIX paths: "/home/…", "/mnt/…", "/Users/…"
+    String.raw `\bsession-[0-9a-f]{8}\b`, // session-scoped identifiers
+    String.raw `~/\.dsh\b`, // user harness home references
+];
+export const DEFAULT_PROMOTION_POLICY = {
+    blockPatterns: DEFAULT_BLOCK_PATTERNS.map((source) => new RegExp(source, "i")),
+    minPromoteChars: 100,
+    maxContentOverlap: 0.6,
+};
+/**
+ * Build a policy from config values (schemastery strings compiled here so
+ * the config layer never touches RegExp). Invalid patterns are skipped —
+ * a broken user pattern must not disable the remaining guards.
+ */
+export function resolvePromotionPolicy(options) {
+    const patterns = [...(options.blockPatterns ?? [])]
+        .map((source) => {
+        try {
+            return new RegExp(source, "i");
+        }
+        catch {
+            return undefined;
+        }
+    })
+        .filter((pattern) => pattern !== undefined);
+    return {
+        blockPatterns: patterns.length > 0 ? patterns : DEFAULT_PROMOTION_POLICY.blockPatterns,
+        minPromoteChars: options.minPromoteChars ?? DEFAULT_PROMOTION_POLICY.minPromoteChars,
+        maxContentOverlap: options.maxContentOverlap ?? DEFAULT_PROMOTION_POLICY.maxContentOverlap,
+    };
+}
+/**
+ * First reason the content reads as project-scoped, or undefined when it
+ * looks portable. Returns the matched pattern source so skip reports stay
+ * explainable in reviews.jsonl rationales.
+ */
+export function projectScopedReason(content, policy) {
+    for (const pattern of policy.blockPatterns) {
+        if (pattern.test(content)) {
+            return `project-scoped content (matches /${pattern.source}/)`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Tokenize for cheap similarity: ASCII words plus CJK character bigrams
+ * (single CJK chars are too ambiguous; bigrams survive segmentation-free
+ * Chinese text). Lowercased; single-char ASCII tokens dropped as noise.
+ */
+export function normalizedTokens(text) {
+    const lowered = text.toLowerCase();
+    const tokens = new Set();
+    for (const match of lowered.matchAll(/[a-z0-9_]{2,}/g)) {
+        tokens.add(match[0] ?? "");
+    }
+    let previous;
+    for (const match of lowered.matchAll(/[\u3400-\u9fff]/g)) {
+        const char = match[0] ?? "";
+        if (previous !== undefined) {
+            tokens.add(`${previous}${char}`);
+        }
+        previous = char;
+    }
+    tokens.delete("");
+    return tokens;
+}
+/** Jaccard similarity of two texts' normalized token sets (0..1). */
+export function contentOverlap(a, b) {
+    const left = normalizedTokens(a);
+    const right = normalizedTokens(b);
+    if (left.size === 0 || right.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const token of left) {
+        if (right.has(token)) {
+            intersection += 1;
+        }
+    }
+    return intersection / (left.size + right.size - intersection);
+}
+/**
+ * The most similar non-archived global entry of the same kind, above the
+ * policy threshold. Title and content both feed the comparison (titles are
+ * short; content carries the real signal).
+ */
+export function mostSimilarGlobalEntry(globalState, kind, title, content, policy) {
+    let best;
+    for (const other of Object.values(globalState.entries[kind])) {
+        if (isArchived(other))
+            continue;
+        const score = Math.max(contentOverlap(title, other.title), contentOverlap(content, other.content));
+        if (score >= policy.maxContentOverlap && (best === undefined || score > best.score)) {
+            best = { id: other.id, title: other.title, score };
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=promotion.js.map

package/lib/service.js

@@ -1,4 +1,5 @@
 import { applyRefinementProposal } from "./apply.js";
+import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
 import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
@@ -9,7 +10,7 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
     function apply(scope, sessionId, proposal, context) {
         const paths = storePaths(baseDir, scope, sessionId);
         const state = context?.baselineState ?? load(scope, sessionId);
-        const id = `evolve_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        const id = `evolve_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
         // Code-enforced snapshot: runs before any mutation, cannot be skipped by the model.
         snapshotBefore(paths, id);
         const result = applyRefinementProposal(state, proposal, {

package/lib/skill-render.d.ts

@@ -10,6 +10,14 @@
 import type { HarnessEntry } from "./types.js";
 /** Convert a harness entry id (underscore slug) to a kebab-case skill name. */
 export declare function skillNameOf(id: string): string;
-/** Render a harness skill entry as a discoverable SKILL.md document. */
+/**
+ * Render a harness skill entry as a discoverable SKILL.md document.
+ *
+ * 2026-08-22: the frontmatter description now carries a ROUTING HINT —
+ * title plus the first meaningful content line — instead of the bare title.
+ * The skill catalog matches on description; a title-only description gave
+ * loaders nothing to route on (observed: materialized skills were 7-line
+ * stubs with a one-line description and no use-when signal).
+ */
 export declare function renderSkillMarkdown(entry: HarnessEntry): string;
 //# sourceMappingURL=skill-render.d.ts.map

package/lib/skill-render.js

@@ -2,12 +2,50 @@
 export function skillNameOf(id) {
     return id.toLowerCase().replace(/_/g, "-");
 }
-/** Render a harness skill entry as a discoverable SKILL.md document. */
+/**
+ * First content line usable as a routing hint: non-empty, not a Markdown
+ * heading, not a list marker, not frontmatter. Undefined when the body is
+ * effectively empty.
+ */
+function routingHint(content) {
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith("#") || line.startsWith("---") || line.startsWith("-") || line.startsWith("*"))
+            continue;
+        return oneLine(line);
+    }
+    return undefined;
+}
+/** Max rendered frontmatter description length (loaders truncate anyway). */
+const MAX_DESCRIPTION_LENGTH = 240;
+/**
+ * Render a harness skill entry as a discoverable SKILL.md document.
+ *
+ * 2026-08-22: the frontmatter description now carries a ROUTING HINT —
+ * title plus the first meaningful content line — instead of the bare title.
+ * The skill catalog matches on description; a title-only description gave
+ * loaders nothing to route on (observed: materialized skills were 7-line
+ * stubs with a one-line description and no use-when signal).
+ */
 export function renderSkillMarkdown(entry) {
+    const hint = routingHint(entry.content);
+    const base = oneLine(entry.title);
+    let description;
+    if (base.length === 0) {
+        description = (hint ?? "").slice(0, MAX_DESCRIPTION_LENGTH);
+    }
+    else if (hint !== undefined && !base.toLowerCase().includes(hint.toLowerCase())) {
+        description = `${base} — use when: ${hint}`.slice(0, MAX_DESCRIPTION_LENGTH);
+    }
+    else {
+        description = base.slice(0, MAX_DESCRIPTION_LENGTH);
+    }
     const lines = [
         "---",
         `name: ${skillNameOf(entry.id)}`,
-        `description: ${oneLine(entry.title)}`,
+        `description: ${description}`,
         "---",
         "",
         entry.content.trim(),

package/lib/state.js

@@ -80,8 +80,13 @@ export function loadHarnessState(stateDir, scope = "global") {
                     scope: normalizeScope(entry["scope"], scope),
                     reference: objectRecord(entry["reference"]) ?? {},
                     arguments: objectRecord(entry["arguments"]) ?? {},
+                    // skill_kind must survive persistence: /evolve mount and the
+                    // listing render branch on it (guidance vs executable).
+                    ...(entry["skill_kind"] === "guidance" || entry["skill_kind"] === "executable"
+                        ? { skill_kind: entry["skill_kind"] }
+                        : {}),
                     metadata: objectRecord(entry["metadata"]) ?? {},
-                    source: entry["source"] === "evolve" ? "evolve" : "evolve",
+                    source: "evolve",
                     created_at: typeof entry["created_at"] === "string" ? entry["created_at"] : new Date(0).toISOString(),
                     updated_at: typeof entry["updated_at"] === "string" ? entry["updated_at"] : new Date(0).toISOString(),
                     version: typeof entry["version"] === "number" ? entry["version"] : 1,

package/lib/usage.d.ts

@@ -2,19 +2,32 @@ import type { HarnessState, RefinementKind } from "./types.js";
 export interface UsageStore {
     /** Injection count per entry key (`kind:id`). */
     counts: Record<string, number>;
+    /** Session dedup marker: the last session id each key was counted in (v2). */
+    lastSession?: Record<string, string>;
 }
-/** Load the usage store from disk; returns an empty store when absent or corrupt. */
+/**
+ * Load the usage store from disk; returns an empty store when absent or
+ * corrupt. Accepts BOTH on-disk shapes:
+ * - legacy (≤0.3.x): a flat `{ "kind:id": count }` map,
+ * - v2: `{ version: 2, counts, lastSession }` with per-session dedup.
+ */
 export declare function loadUsage(baseDir: string): UsageStore;
-/** Persist the usage store atomically. */
+/** Persist the usage store atomically (always the v2 shape). */
 export declare function saveUsage(baseDir: string, store: UsageStore): void;
 /** Build the usage key for an entry. */
 export declare function usageKey(kind: RefinementKind, id: string): string;
 /**
  * Increment injection counts for the entries that were actually injected.
  * Called after `entriesSectionText` renders the injected block. Keys not
- * present in the store are initialized to 1; existing keys are incremented.
+ * present in the store are initialized to 1.
+ *
+ * Session dedup (2026-08-22): with a sessionId, each key counts AT MOST
+ * ONCE per session — the old per-build counting produced meaningless
+ * numbers (one entry hit 2311× in a week) and hid the real "how many
+ * sessions found this useful" signal that staleness decay needs. Without
+ * a sessionId the call degrades to legacy always-increment behavior.
  */
-export declare function recordInjection(baseDir: string, injectedKeys: string[]): void;
+export declare function recordInjection(baseDir: string, injectedKeys: readonly string[], sessionId?: string): void;
 /**
  * Get the injection count for a specific entry. Returns 0 when the entry
  * has never been injected (absent from the store).