@lmzhen/dsh-evolution-core 0.1.0-rc.4 → 0.1.0-rc.41

package/lib/types/constants.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared constants for the dsh-evolution plugin family.
+ *
+ * Two classes of value live here, deliberately separated by section so future
+ * edits do not blur the semantic boundary:
+ *
+ * 1. **Fixed protocol/format/security invariants** — changing these breaks an
+ *    on-disk format, a naming/format contract, a path-security boundary, or a
+ *    cross-component invariant. They are NOT exposed as deployment config.
+ *
+ * 2. **Cross-package shared tunable defaults** — the same semantic default is
+ *    read (with a config override path) by more than one package (e.g.
+ *    `evolution-policy` and `evolution-curator` both default `staleAfterDays`
+ *    to 30). Centralizing them here means one authoritative default: a config
+ *    override still applies per package, but the fallback is single-sourced.
+ *
+ * Package-private tunables (used by exactly one package) stay in that package,
+ * not here — see evolution-replay's `DEFAULT_WEIGHTS` and evolution-feedback's
+ * threshold, which are intentionally left where they are used.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+/** Skill frontmatter `name` validated for the file name (lowercase + hyphen). */
+export declare const SKILL_NAME_RE: RegExp;
+/** Allowed skill support-file subdirectories (path-traversal boundary). */
+export declare const SUPPORT_DIRS: readonly ["references", "templates", "scripts", "assets"];
+/** Delimiter between durable memory entries (on-disk storage format). */
+export declare const ENTRY_DELIMITER = "\n\u00A7\n";
+/** Built-in skill names the curator must never lifecycle-manage. */
+export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
+export declare const MAX_SKILL_NAME_LENGTH = 64;
+export declare const MAX_DESCRIPTION_LENGTH = 1024;
+export declare const MAX_SKILL_CONTENT_CHARS = 100000;
+export declare const MAX_SKILL_FILE_BYTES = 1048576;
+export declare const DEFAULT_REVIEW_MEMORY_INTERVAL = 10;
+export declare const DEFAULT_REVIEW_SKILL_INTERVAL = 10;
+/** Skill-review completion channel trigger mode: 'cadence' | 'completion' | 'both'. */
+export declare const DEFAULT_SKILL_REVIEW_TRIGGER: "both";
+/** Cumulative session tool calls before a session counts as "proven long" for the completion channel. */
+export declare const DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS = 20;
+export declare const DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS = 3;
+export declare const DEFAULT_SUBSTANTIVE_MIN_USER_CHARS = 200;
+export declare const DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS = 500;
+export declare const DEFAULT_MAX_OPS_PER_PLAN = 32;
+export declare const DEFAULT_CURATOR_INTERVAL_HOURS = 168;
+export declare const DEFAULT_MIN_IDLE_HOURS = 2;
+export declare const DEFAULT_STALE_AFTER_DAYS = 30;
+export declare const DEFAULT_ARCHIVE_AFTER_DAYS = 90;
+export declare const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
+export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
+export declare const DEFAULT_SKILL_CONTENT_CHARS = 100000;
+//# sourceMappingURL=constants.d.ts.map

package/lib/types/curator.d.ts

@@ -1,8 +1,12 @@
 /**
  * Deterministic skill curator: active → stale → archived transitions.
- * Pure function; file moves are performed by SkillLibrary.
+ * Pure function with one deliberate side effect: records in the passed
+ * `usage` map are MUTATED (state/archived_at) to carry the transition — the
+ * caller owns the map and decides whether to clone first (dry-run) or persist
+ * after. File moves are performed by SkillLibrary.
  */
-import type { UsageMap } from './usage.ts';
+import type { UsageMap, UsageRecord } from './usage.ts';
+export { PROTECTED_BUILTIN_SKILLS } from './constants.ts';
 export interface CuratorConfig {
     staleAfterDays: number;
     archiveAfterDays: number;
@@ -12,6 +16,14 @@ export interface CuratorConfig {
     excludeSkillNames?: ReadonlySet<string>;
     /** When true, usage records without created_by='agent' also enter the lifecycle. */
     manageUnmanaged?: boolean;
+    /** When true, bundled skills (in `bundledNames`) are curation candidates like agent-created ones. */
+    pruneBuiltins?: boolean;
+    /** Skill names carrying the bundled marker; only read when `pruneBuiltins` is true. */
+    bundledNames?: ReadonlySet<string>;
+    /** Skill names the curator archived once and must not fight across re-seeds. */
+    suppressedNames?: ReadonlySet<string>;
+    /** Skills referenced by scheduled/automated jobs: never auto-transitioned (idle clocks mislead for rarely-firing tasks). */
+    referencedSkillNames?: ReadonlySet<string>;
 }
 export interface CuratorTransition {
     name: string;
@@ -25,7 +37,6 @@ export interface CuratorResult {
     reactivate: string[];
     markStale: string[];
 }
-export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
 export interface CuratorArchivedSkill {
     name: string;
     path: string;
@@ -36,6 +47,8 @@ export interface CuratorFailedSkill {
     reason: string;
 }
 export interface CuratorRunReport {
+    /** Report shape version; readers may ignore unknown fields on later versions. */
+    schemaVersion: 1;
     runId: string;
     startedAt: string;
     finishedAt: string;
@@ -45,6 +58,8 @@ export interface CuratorRunReport {
     archived: CuratorArchivedSkill[];
     failed: CuratorFailedSkill[];
     snapshotPath?: string;
+    /** Whether the LLM nomination pass was enabled for this run (decision visibility). */
+    llmReviewEnabled?: boolean;
 }
 export interface CuratorReportInput {
     runId: string;
@@ -56,7 +71,49 @@ export interface CuratorReportInput {
     archived: readonly CuratorArchivedSkill[];
     failed: readonly CuratorFailedSkill[];
     snapshotPath?: string;
+    llmReviewEnabled?: boolean;
 }
 export declare function buildCuratorRunReport(input: CuratorReportInput): CuratorRunReport;
+/** One LLM-nominated consolidation: `from` merges into the umbrella `into`. */
+export interface CuratorConsolidation {
+    from: string;
+    into: string;
+}
+/** Structured result of the optional curator LLM nomination pass. */
+export interface CuratorNominations {
+    prunings: string[];
+    consolidations: CuratorConsolidation[];
+}
+/**
+ * Parse the curator LLM's YAML nomination block (consolidations + prunings).
+ * Line-oriented and lenient by design: the LLM output is advisory, every name
+ * is re-validated against the tree before any file move happens downstream.
+ */
+export declare function parseCuratorNominations(text: string): CuratorNominations;
+/**
+ * The lifecycle-candidate gate, shared by the transition engine and the scope
+ * view so the two can never disagree: records failing ANY of these gates are
+ * outside the managed scope.
+ */
+export declare function lifecycleCandidate(name: string, record: UsageRecord, config: CuratorConfig, bundled: boolean): boolean;
+export interface ScopeView {
+    /** Skills inside the lifecycle scope right now (candidate gate + active state). */
+    managed: string[];
+    /** Managed skills already flagged stale or quality-warned — the ones to watch. */
+    watched: string[];
+    /** Managed skills flagged low quality (subset of `watched`) — consolidation candidates. */
+    qualityWarned: string[];
+    /** Explicitly exempted by excludeSkillNames / referencedSkillNames. */
+    exempted: string[];
+    /** Carrying a protection marker (pinned / bundled / hub-installed). */
+    protected: string[];
+}
+/**
+ * Read-only scope classification, derived from the SAME gate the transition
+ * engine uses (`lifecycleCandidate`), so the view always predicts what a
+ * curator pass may touch. `protectedNames` carries the marker info the usage
+ * records lack (bundled / hub-installed / pinned from `SkillLibrary.list()`).
+ */
+export declare function computeScopeView(usage: UsageMap, config: CuratorConfig, protectedNames?: ReadonlyMap<string, string>): ScopeView;
 export declare function computeLifecycleTransitions(usage: UsageMap, config: CuratorConfig, now?: Date): CuratorResult;
 //# sourceMappingURL=curator.d.ts.map

package/lib/types/index.d.ts

@@ -10,11 +10,15 @@
 export * from './curator.ts';
 export * from './events.ts';
 export * from './io.ts';
+export * from './learn-prompt.ts';
 export * from './memory-store.ts';
+export * from './mutations.ts';
 export * from './prompts.ts';
+export * from './quality.ts';
 export * from './signals.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';
 export * from './threats.ts';
 export * from './usage.ts';
+export * from './constants.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/io.d.ts

@@ -13,10 +13,15 @@ export interface EvolutionIoLike {
     exists(path: string): Promise<boolean>;
     rename(path: string, destination: string): Promise<void>;
     copy(path: string, destination: string): Promise<void>;
+    /**
+     * Optional byte-size probe for the read guard. Return the file's size in
+     * bytes, or `null`/`undefined` when unknown (unsupported backend, missing
+     * file, stat failure). An implementation without this probe gets no guard:
+     * consumers treat an unknown size as "guard not applicable".
+     */
+    size?(path: string): Promise<number | null>;
 }
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;
 export declare function nodeEvolutionIo(): EvolutionIoLike;
-/** Absolute path helper kept separate so stores stay platform-correct. */
-export declare function childPath(parent: string, ...parts: string[]): string;
 //# sourceMappingURL=io.d.ts.map

package/lib/types/learn-prompt.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Open-ended `/evolution learn` prompt builder.
+ *
+ * `learn` is open-ended: the user can name anything they can describe — a
+ * directory of code, an API doc URL, a workflow they just walked the agent
+ * through, or pasted notes. The prompt instructs the live agent to gather the
+ * named sources with its existing tools, then author a single SKILL.md via
+ * `skill_manage` following `DSH_AUTHORING_STANDARDS`. There is no separate
+ * distillation engine and no model-tool footprint.
+ */
+/**
+ * Build the agent prompt for an open-ended `/evolution learn` request.
+ *
+ * @param userRequest free-text the user gave after `/evolution learn`; an
+ *   empty string falls back to "the workflow we just went through".
+ * @returns a complete instruction the agent runs as a normal turn.
+ */
+export declare function buildLearnPrompt(userRequest: string): string;
+//# sourceMappingURL=learn-prompt.d.ts.map

package/lib/types/memory-store.d.ts

@@ -3,7 +3,7 @@
  * Stores are MEMORY.md and USER.md under $DSH_HOME/memories (~/.dsh/memories).
  */
 import { type EvolutionIoLike } from './io.ts';
-export declare const ENTRY_DELIMITER = "\n\u00A7\n";
+export { ENTRY_DELIMITER } from './constants.ts';
 export type MemoryTarget = 'memory' | 'user';
 export interface MemoryOperation {
     action: 'add' | 'replace' | 'remove';
@@ -37,24 +37,53 @@ export declare class MemoryStore {
     private failureCount;
     constructor(options?: MemoryStoreOptions);
     limitFor(target: MemoryTarget): number;
+    /**
+     * Read-guard probe: `{ size, limit }` when the on-disk file exceeds
+     * `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown
+     * (backend without a size probe), under the bound, or the target has no
+     * limit configured.
+     */
+    private oversizedFile;
     read(target: MemoryTarget): Promise<string[]>;
     write(target: MemoryTarget, entries: string[]): Promise<void>;
     resetFailures(): void;
     private failure;
+    /**
+     * StorageHint percentage must clamp at 100 like the render header: a drifted
+     * entry can push chars past the limit, and "Storage at 125%" contradicts the
+     * clamped usage indicator.
+     */
+    private storageHint;
+    /**
+     * Best-effort raw-copy backup of the on-disk file to `<file>.bak.<stamp>`
+     * before a refusal, so an externally modified (or oversized) file stays
+     * recoverable. Copies bytes instead of reading them so a pathologically
+     * large file is never loaded just to back it up. Failure to back up does
+     * not change the refusal semantics.
+     */
+    private backupFile;
+    /**
+     * Read-guard refusal for write paths. Returns the refusal result when the
+     * target file is oversized, `null` otherwise. The file is skipped for
+     * reading (never loaded), backed up by raw copy, and the model is told to
+     * fix it manually — mirroring the drift refusal so corrupted state is never
+     * silently overwritten.
+     */
+    private oversizedRefusal;
     add(target: MemoryTarget, facts: string): Promise<MemoryApplyResult>;
     replace(target: MemoryTarget, oldText: string, facts: string): Promise<MemoryApplyResult>;
     remove(target: MemoryTarget, oldText: string): Promise<MemoryApplyResult>;
     private mutate;
     applyBatch(target: MemoryTarget, operations: MemoryOperation[]): Promise<MemoryApplyResult>;
     renderContext(): Promise<string>;
-    snapshot(): Promise<{
-        memory: string[];
-        user: string[];
-    }>;
-    restoreSnapshot(snapshot: {
-        memory: string[];
-        user: string[];
-    }): Promise<void>;
+    /**
+     * Detect on-disk drift: true when the file is not in the canonical
+     * `render(normalizeEntries(raw))` form. This catches structural anomalies
+     * the writer would quietly normalize away (empty/`§`-only entries, stray
+     * blank lines, leading/trailing delimiters) that indicate the file was
+     * edited outside MemoryStore. Purely single-canonical content reaches the
+     * same serialization and returns false, so a normal write is never flagged.
+     */
     detectDrift(target: MemoryTarget): Promise<boolean>;
 }
 //# sourceMappingURL=memory-store.d.ts.map

package/lib/types/mutations.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Curator/author audit trail: `.mutations.json` records every skill mutation
+ * with before/after content hashes so any automated edit is reviewable and
+ * replayable. Best-effort persistence, mirroring the usage sidecar posture.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+import { type EvolutionIoLike } from './io.ts';
+export interface MutationRecord {
+    skillName: string;
+    action: string;
+    beforeHash?: string;
+    afterHash?: string;
+    summary: string;
+    at: string;
+}
+export declare const DEFAULT_MUTATION_CAP = 500;
+/** Version of the `.mutations.json` file shape; writers always emit the current one. */
+export declare const MUTATIONS_FILE_VERSION = 1;
+export declare function mutationsFile(root: string): string;
+export declare function contentHash(content: string): string;
+export declare function loadMutations(root: string, io?: EvolutionIoLike): Promise<MutationRecord[]>;
+/** Append one record, trim to `cap`, and write atomically (versioned shape). */
+export declare function recordMutation(root: string, io: EvolutionIoLike, record: MutationRecord, cap?: number): Promise<void>;
+//# sourceMappingURL=mutations.d.ts.map

package/lib/types/prompts.d.ts

@@ -1,8 +1,16 @@
-export declare const PROMPT_BUNDLE_ID = "dsh-evolution@1";
+/**
+ * Prompt bundle identity. Bump both id and version whenever a prompt's text
+ * changes semantically: the bundle digest is the fail-closed signal for
+ * review workers, so a stale id across deployments must be distinguishable.
+ */
+export declare const PROMPT_BUNDLE_ID = "dsh-evolution@2";
+export declare const PROMPT_BUNDLE_VERSION = 2;
 export declare const MEMORY_REVIEW_PROMPT = "[Auto-review \u2014 Memory]\nReview the conversation above and consider saving to memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?\n\nIf something stands out, save it using the memory tool.\nIf nothing is worth saving, just say \"Nothing to save.\" and stop.";
 export declare const SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills]\nReview the conversation above and update the skill library. Be ACTIVE \u2014 most sessions produce at least one skill update, even if small.\n\nTarget shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.\n\nSignals that warrant action:\n- The user corrected your style, tone, format, verbosity, workflow, or approach.\n- A non-trivial technique, fix, workaround, or debugging path emerged.\n- A loaded skill turned out wrong, missing, or outdated \u2014 patch it now.\n\nPreference order:\n1. Patch a skill that was loaded or read this session.\n2. Patch an existing umbrella skill.\n3. Add references/, templates/, or scripts/ support under an existing skill.\n4. Create a new class-level umbrella skill only when nothing fits.\n\nProtected skills (bundled/hub-installed) must not be edited. Pinned skills may be patched but not archived.\n\nDo NOT capture:\n- Environment-dependent failures (missing binaries, unconfigured credentials).\n- Negative claims about tools (\"browser tools do not work\").\n- Transient errors that resolved during the session.\n- One-off task narratives.\n\nIf a tool failed because of setup state, capture the FIX under an existing setup skill \u2014 never \"this tool does not work\" as a standalone constraint.\n\n\"Nothing to save.\" is a real option but should NOT be the default.";
 export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things.\n\n**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.\n\n**Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.\n\nAct on whichever dimension has real signal. If genuinely nothing stands out on either, say \"Nothing to save.\" and stop \u2014 but don't reach for that conclusion as a default.";
-export declare const CURATOR_PROMPT = "You are the skill curator. Maintain a healthy, class-level skill library.\n\nRules:\n1. NEVER hard-delete a skill. Archive is the maximum destructive action.\n2. Do not touch bundled, hub-installed, or pinned skills.\n3. Do not archive recently-created or never-used skills without strong evidence.\n4. Prefer merging narrow skills into class-level umbrellas.\n5. Before archiving a merged skill, ensure its unique content was preserved.\n\nProduce a YAML summary:\nconsolidations:\n  - from: <old-skill-name>\n    into: <umbrella-skill-name>\n    reason: <one short sentence>\nprunings:\n  - name: <skill-name>\n    reason: <one short sentence>";
+export declare const CURATOR_PROMPT = "You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.\n\nThe goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.\n\nRight target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.\n\nHard rules:\n1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.\n2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (`referenced`) skills. Referenced skills MAY be consolidated into an umbrella, but never simply pruned.\n3. Do not archive recently-created or never-used skills without strong evidence. \"use=0\" is NOT evidence either way \u2014 it only means the trigger has not come up yet.\n4. Do NOT reject consolidation on the grounds that \"each skill has a distinct trigger\". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.\n5. Judge overlap on CONTENT, not on usage counters.\n6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.\n\nHow to work:\n1. Scan the candidate list. Identify PREFIX CLUSTERS \u2014 skills sharing a first word or domain keyword (expect 10-25 clusters).\n2. For each cluster with 2+ members, ask \"what is the UMBRELLA CLASS these skills serve?\" and consolidate:\n   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).\n   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.\n   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella.\n3. Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.\n\nProduce a YAML summary with exactly this shape:\nconsolidations:\n  - from: <old-skill-name>\n    into: <umbrella-skill-name>\n    reason: <one short sentence>\nprunings:\n  - name: <skill-name>\n    reason: <one short sentence>\nNominate a pruning only when archival is clearly safe (stale AND genuinely obsolete or fully absorbed elsewhere).";
+export declare const CURATOR_DRY_RUN_BANNER = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nDRY-RUN \u2014 REPORT ONLY. DO NOT MUTATE THE SKILL LIBRARY.\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\nThis is a PREVIEW pass. Follow every instruction above EXCEPT:\n  \u2022 Do NOT call skill_manage with action=create, update, patch, delete, write_file, or remove_file.\n  \u2022 Do NOT move, copy, or rewrite any file under the skills tree.\n\nYour output IS the deliverable: produce the exact same human-readable summary and YAML block you would on a live run, describing the actions you WOULD take. A reviewer will decide whether to approve a live run.\n\nIf you accidentally take a mutating action, say so explicitly in the summary.";
+export declare const COMPLETION_SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills \u00B7 task complete]\nYour current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.\n\nFollow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch skills loaded this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.\n\nDo NOT modify output files or re-run the task. If you are still mid-task, ignore this.";
 export declare function reviewPrompt(kind: 'memory' | 'skill' | 'combined'): string;
 export interface PromptBundle {
     id: string;
@@ -12,5 +20,5 @@ export interface PromptBundle {
 }
 export declare const PROMPT_BUNDLE: PromptBundle;
 export declare function verifyPromptBundle(bundle?: PromptBundle): boolean;
-export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## When to Use\" \u2014 concrete trigger phrases.\n3. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n4. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n5. \"## Quick Reference\" \u2014 flat command/endpoint list.\n6. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n7. \"## Pitfalls\" \u2014 known limits and rate limits.\n8. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.";
+export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n- metadata.hermes.related_skills: [a, b] \u2014 name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## When to Use\" \u2014 concrete trigger phrases.\n3. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n4. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n5. \"## Quick Reference\" \u2014 flat command/endpoint list.\n6. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n7. \"## Pitfalls\" \u2014 known limits and rate limits.\n8. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.";
 //# sourceMappingURL=prompts.d.ts.map

package/lib/types/quality.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Quality scoring and near-duplicate detection for the curated skill library.
+ *
+ * Pure functions over data inputs so the scoring policy is unit-testable and
+ * the same math feeds the usage sidecar, the `skill_manage review` surface and
+ * the learning graph. Weights follow the Hermes/hermes-claw six-factor model;
+ * mutation maturity is a documented DSH approximation (single per-month patch
+ * trend ratio replaces the claw timestamp-trend formula, since DSH usage
+ * records only carry the last patched timestamp).
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+import type { UsageMap } from './usage.ts';
+export interface QualityFactors {
+    /** 0.25 — use_count per day of age, capped at 1. */
+    usageFrequency: number;
+    /** 0.20 — 1 − patch/use (zero use = stable). */
+    stability: number;
+    /** 0.20 — 1 under 30 idle days, linear decay to 0 at 180. */
+    recency: number;
+    /** 0.10 — in-degree / 3 (graph references), capped at 1. */
+    references: number;
+    /** 0.20 — patch cadence maturity (DSH approximation of the trend formula). */
+    mutationMaturity: number;
+    /** 0.05 — non-empty support subdirectories × 0.175, capped at 1. */
+    richness: number;
+}
+export interface QualityScore {
+    score: number;
+    factors: QualityFactors;
+    warn: boolean;
+}
+export declare const QUALITY_WEIGHTS: {
+    readonly usageFrequency: 0.25;
+    readonly stability: 0.2;
+    readonly recency: 0.2;
+    readonly references: 0.1;
+    readonly mutationMaturity: 0.2;
+    readonly richness: 0.05;
+};
+/** Score below which a skill is flagged for review. */
+export declare const LOW_QUALITY_THRESHOLD = 0.3;
+export declare function computeQualityScores(input: {
+    usage: UsageMap;
+    referenceCounts?: ReadonlyMap<string, number>;
+    supportDirs?: ReadonlyMap<string, number>;
+    now?: Date;
+}): Map<string, QualityScore>;
+/**
+ * Two-phase near-duplicate clustering: exact normalized-hash groups first,
+ * then token-Jaccard edges at {@link DEDUP_SIMILARITY_THRESHOLD} with a token
+ * ratio guard, union-find across the whole set.
+ */
+export declare function computeDedupGroups(input: {
+    contents: ReadonlyMap<string, string>;
+    threshold?: number;
+}): string[][];
+//# sourceMappingURL=quality.d.ts.map

package/lib/types/skill-store.d.ts

@@ -7,11 +7,7 @@
  * move to `.archive/` — never a hard delete.
  */
 import { type EvolutionIoLike } from './io.ts';
-export declare const SKILL_NAME_RE: RegExp;
-export declare const MAX_SKILL_NAME_LENGTH = 64;
-export declare const MAX_DESCRIPTION_LENGTH = 1024;
-export declare const MAX_SKILL_CONTENT_CHARS = 100000;
-export declare const MAX_SKILL_FILE_BYTES = 1048576;
+import { type MutationRecord } from './mutations.ts';
 export interface SkillLimits {
     maxNameLength: number;
     maxDescriptionLength: number;
@@ -19,7 +15,6 @@ export interface SkillLimits {
     maxSkillFileBytes: number;
 }
 export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
-export declare const SUPPORT_DIRS: readonly ["references", "templates", "scripts", "assets"];
 export interface SkillSummary {
     name: string;
     description: string;
@@ -33,6 +28,37 @@ export interface SkillActionResult {
     message: string;
     path?: string;
 }
+/** Extra file name carried inside a snapshot's `extras/` directory. */
+export declare const SNAPSHOT_EXTRA_NAME_RE: RegExp;
+/** An opaque side file stored under a snapshot's `extras/` (curator state etc.). */
+export interface SnapshotExtra {
+    name: string;
+    content: string;
+}
+/** Normalized manifest of a skills snapshot. */
+export interface SnapshotManifest {
+    reason: string;
+    createdAt: string;
+    /** Active skill names at snapshot time. */
+    skills: string[];
+    /** Co-copied sidecar file names (usage/suppression). */
+    sidecars: string[];
+    /** Whether `.archive/` was co-copied; absent on legacy manifests (do not touch archive on restore). */
+    hasArchive?: boolean;
+    /** Extras declared under `extras/`; only these names are ever read back. */
+    extras: string[];
+}
+/** Who is writing: a foreground user-directed tool call, or the autonomous review/curator pipeline. */
+export type WriteOrigin = 'foreground' | 'subagent' | 'background_review';
+/** Options for `SkillLibrary.archive`. The absorbed-into name and the archival reason are distinct fields. */
+export interface ArchiveOptions {
+    /** Umbrella skill this one was consolidated into; when set it must exist (consolidate semantics). */
+    absorbedInto?: string;
+    /** Human-readable reason written to `.archive-reason`; default derives from `absorbedInto`. */
+    reason?: string;
+    /** Permit archiving a bundled skill (curator prune-builtins only; hub-installed and pinned stay protected). */
+    allowBundled?: boolean;
+}
 export declare function skillsRoot(env?: NodeJS.ProcessEnv): string;
 export interface Frontmatter {
     name?: string;
@@ -51,21 +77,78 @@ export declare class SkillLibrary {
     constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits);
     list(): Promise<SkillSummary[]>;
     read(name: string): Promise<string | null>;
-    writeProtection(name: string): Promise<string | null>;
-    deleteProtection(name: string): Promise<string | null>;
+    /** Name-format guard shared by every path-building mutator/reader. */
+    private badName;
+    writeProtection(name: string, origin?: WriteOrigin): Promise<string | null>;
+    deleteProtection(name: string, options?: {
+        allowBundled?: boolean;
+    }): Promise<string | null>;
     isManaged(name: string): Promise<boolean>;
-    create(name: string, content: string, origin: 'foreground' | 'background_review'): Promise<SkillActionResult>;
-    update(name: string, content: string): Promise<SkillActionResult>;
-    patch(name: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean): Promise<SkillActionResult>;
-    archive(name: string, absorbedInto?: string): Promise<SkillActionResult>;
-    writeSupportFile(name: string, filePath: string, content: string): Promise<SkillActionResult>;
-    removeSupportFile(name: string, filePath: string): Promise<SkillActionResult>;
-    snapshotAll(reason?: string): Promise<string>;
+    /** Whether the skill carries the bundled marker (curator prune-builtins eligibility). */
+    isBundled(name: string): Promise<boolean>;
+    /** Whether the skill carries the pinned marker (the marker is the factual source; usage.pinned mirrors it). */
+    isPinned(name: string): Promise<boolean>;
+    /** Count non-empty support subdirectories (richness input for quality scoring). */
+    countSupportDirs(name: string): Promise<number>;
+    /** Best-effort audit trail entry; never blocks the mutation. */
+    private audit;
+    /** Recent mutation audit records (read-only inspection surface). */
+    listMutations(): Promise<MutationRecord[]>;
+    /**
+     * Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
+     * deletion, from background-review writes, and from the lifecycle — a
+     * protective mutation, so the autonomous pipeline may never call it. The
+     * marker write is the only state change; content is untouched.
+     */
+    setPinned(name: string, pinned: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    create(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    update(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    patch(name: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    archive(name: string, options?: ArchiveOptions): Promise<SkillActionResult>;
+    /**
+     * Merge the bodies of `sources` into `target` and archive the sources with
+     * an absorbed-into marker. Hermes-style consolidation: overlapping skills
+     * collapse into one, and the originals stay recoverable under `.archive/`.
+     */
+    consolidate(target: string, sources: string[], origin?: WriteOrigin): Promise<SkillActionResult>;
+    /**
+     * Restore one skill from `.archive/` back to the active root. Hermes-style
+     * recoverability: archival never deletes, and this is the control-plane
+     * path back. The `.archive-reason` marker is dropped on restore.
+     */
+    restoreFromArchive(name: string): Promise<SkillActionResult>;
+    writeSupportFile(name: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    removeSupportFile(name: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    /**
+     * Snapshot the recoverable skills state: active tree, usage/suppression
+     * sidecars, `.archive/` and caller-supplied extras. `extras` are opaque
+     * side files the Snapshot owner cares about (curator state); they are
+     * listed in the manifest and only those names are ever read back.
+     */
+    snapshotAll(reason?: string, extras?: SnapshotExtra[]): Promise<string>;
+    /** Read and normalize a snapshot manifest; null when the file is missing or unparsable. */
+    readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
+    /** Keep only the newest N snapshots (Hermes keep=5 parity); oldest folded into .backups history. */
+    private retainSnapshots;
     listSnapshots(): Promise<Array<{
         path: string;
         createdAt: string;
         reason: string;
     }>>;
-    restoreLatestSnapshot(): Promise<SkillActionResult>;
+    /**
+     * Read the extras of a snapshot, restricted to the names declared in the
+     * manifest — an `extras/` directory is never listed directly, so unknown
+     * files cannot leak back as state on the next restore.
+     */
+    readSnapshotExtras(path: string): Promise<SnapshotExtra[]>;
+    /**
+     * Manifest-driven restore of the latest snapshot: active tree, sidecars,
+     * `.archive/` and (for full-state snapshots) the extras read back by the
+     * caller. `extras` are additionally written into the pre-rollback safety
+     * snapshot so the rollback itself is undoable with the same state.
+     */
+    restoreLatestSnapshot(extras?: SnapshotExtra[]): Promise<SkillActionResult & {
+        extras?: SnapshotExtra[];
+    }>;
 }
 //# sourceMappingURL=skill-store.d.ts.map

package/lib/types/state-store.d.ts

@@ -8,6 +8,13 @@ export declare class JsonState<T> {
     readonly path: string;
     private value;
     constructor(name: string, initial: T, env?: NodeJS.ProcessEnv);
+    /**
+     * Deep-merge persisted state over the initial defaults. Nested plain
+     * objects merge recursively (so a new default field added under an existing
+     * object is preserved), while arrays and primitives take the on-disk value
+     * wholesale. Keeps forward-compatible defaults across schema additions.
+     */
+    private static mergeDeep;
     private loadSync;
     get(): T;
     set(value: T): void;

package/lib/types/threats.d.ts

@@ -12,17 +12,29 @@ export interface ThreatFinding {
     category: string;
     scope: ThreatScope;
 }
+/**
+ * Optional scan controls. Default behavior (`options` omitted) is unchanged:
+ * every in-scope pattern blocks. Adapters that need to tolerate a specific
+ * benign phrasing (e.g. a skill that legitimately opens with "You are now a ...")
+ * can exclude that label by name here. This is opt-in and never widens strict
+ * scope; it only permits callers to drop a known-innocent match.
+ */
+export interface ScanOptions {
+    /** Pattern labels to skip during this scan. */
+    excludeLabels?: readonly string[];
+}
 /**
  * Scan text at `scope`. Patterns are cumulative: `strict` includes all scopes.
+ * `options.excludeLabels` removes matching patterns without changing `scope`.
  */
-export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number): ThreatFinding[];
+export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): ThreatFinding[];
 /** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
-export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number): {
+export declare function evaluateThreat(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): {
     blocked: boolean;
     findings: ThreatFinding[];
 };
 /** User-facing block message for memory writes. */
-export declare function scanMemoryThreats(text: string, maxScanChars?: number): string | null;
+export declare function scanMemoryThreats(text: string, maxScanChars?: number, options?: ScanOptions): string | null;
 /** User-facing block message for skill content writes. */
-export declare function scanContentThreats(text: string, maxScanChars?: number): string | null;
+export declare function scanContentThreats(text: string, maxScanChars?: number, options?: ScanOptions): string | null;
 //# sourceMappingURL=threats.d.ts.map

package/lib/types/usage.d.ts

@@ -30,4 +30,14 @@ export declare function bumpUse(map: UsageMap, name: string, when?: Date): void;
 export declare function bumpPatch(map: UsageMap, name: string, when?: Date): void;
 export declare function markAgentCreated(map: UsageMap, name: string): void;
 export declare function latestActivityAt(record: UsageRecord): string | null;
+/**
+ * Curator suppression sidecar: built-in skills the curator has archived stay
+ * suppressed across re-seeds, so the lifecycle never fights a re-created
+ * bundled skill. Best-effort load/save, mirroring the usage sidecar posture.
+ * Versioned shape ({ version, names }) with legacy plain-array compat.
+ */
+export declare const SUPPRESSED_FILE_VERSION = 1;
+export declare function suppressedFile(root: string): string;
+export declare function loadSuppressedNames(root: string, io?: EvolutionIoLike): Promise<ReadonlySet<string>>;
+export declare function saveSuppressedNames(root: string, names: ReadonlySet<string>, io?: EvolutionIoLike): Promise<void>;
 //# sourceMappingURL=usage.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.41",
   "publishConfig": {
     "access": "public"
   },