@lmzhen/dsh-evolution-core 0.1.0-rc.9 → 0.1.0

package/lib/types/prompts.d.ts

@@ -1,9 +1,29 @@
-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@7";
+export declare const PROMPT_BUNDLE_VERSION = 7;
 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 function reviewPrompt(kind: 'memory' | 'skill' | 'combined'): string;
+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. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update.\n\nSignals to look for (any one of these warrants action):\n  \u2022 User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing.\n  \u2022 User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task.\n  \u2022 Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.\n  \u2022 A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.\n\nRead-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session \u2014 ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.\n\nPreference order \u2014 prefer the earliest action that fits, but do pick one when a signal above fired:\n  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.\n  2. UPDATE AN EXISTING UMBRELLA. If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.\n  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files \u2014 use the right directory per kind:\n     \u2022 references/<topic>.md \u2014 session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs.\n     \u2022 templates/<name>.<ext> \u2014 starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).\n     \u2022 scripts/<name>.<ext> \u2014 statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time).\n     Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists.\n  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong \u2014 fall back to (1), (2), or (3).\n\nUser-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson.\n\nIf you notice two existing skills that overlap, note it in your reply \u2014 the background curator handles consolidation at scale.\n\nTwo-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:\n  \u2022 PATTERN (reusable \u2014 symptom \u2192 mechanism \u2192 fix \u2192 verification, still valuable next session) belongs in the SKILL.md body.\n  \u2022 LOG (one-off \u2014 commit SHAs, npm/profile states, what this release changed, this session's process narrative) belongs in a references/ file, never the body. Body density IS reuse rate. Keep new entries tight: a pattern fits in 2-8 physical lines; prefer changing the current-state pointer over appending history.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.\n\nIf a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting 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. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.";
+export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things:\n\n**Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool.\n\n**Skills**: how to do this class of task. Be ACTIVE \u2014 most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries.\n\nSignals that warrant a skill update (any one is enough):\n  \u2022 User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' \u2014 embed the lesson in the skill that governs that task so the next session starts fixed.\n  \u2022 Non-trivial technique, fix, workaround, or debugging path emerged.\n  \u2022 A skill that was loaded or consulted turned out wrong, missing, or outdated \u2014 patch it now.\n\nRead-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session \u2014 ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.\n\nPreference order for skills \u2014 pick the earliest that fits:\n  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.\n  2. UPDATE AN EXISTING UMBRELLA. Patch it.\n  3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: references/<topic>.md for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; templates/<name>.<ext> for starter files meant to be copied and modified; scripts/<name>.<ext> for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them.\n  4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level \u2014 NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3).\n\nTwo-tier deposition discipline (DSH addition): classify before writing \u2014 PATTERN (symptom \u2192 mechanism \u2192 fix \u2192 verification) goes in the SKILL.md body; LOG (commit SHAs, npm/profile states, this release's change list, this session's narrative) goes in a references/ file. Body density IS reuse rate; a pattern fits in 2-8 physical lines.\n\nUser-preference embedding: when the user complains about how you handled a task, update the skill that governs that task \u2014 memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant.\n\nIf you notice overlapping existing skills, mention it \u2014 the background curator handles consolidation.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.\n\nIf a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill \u2014 never 'this tool does not work' as a standalone constraint.\n\nAct on whichever of the two dimensions 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, not a flat pile of narrow one-session skills.\n\nThis is an UMBRELLA-BUILDING consolidation pass, not a passive audit and not a duplicate-finder.\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 are fully protected \u2014 never consolidated, never pruned (there is no scheduled-task reference-rewriting pass; a referenced skill stays in place by design).\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. Never archive a never-used skill unless it is at least 30 days old AND its content is genuinely obsolete or fully absorbed elsewhere.\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. Expected cluster count scales with the library: a large collection may show 10-25 prefix clusters, a small one often has none \u2014 a clean \"nothing to consolidate\" summary is the correct small-library outcome, not a shortage of ambition.\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. Use the right directory per kind:\n      \u2022 references/<topic>.md \u2014 session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes, provider quirks, reproduction recipes) written concise and task-focused.\n      \u2022 templates/<name>.<ext> \u2014 starter files meant to be copied and modified.\n      \u2022 scripts/<name>.<ext> \u2014 statically re-runnable actions (verification scripts, fixture generators, probes).\n3. Package integrity \u2014 not optional: inspect each skill as a COMPLETE directory package, not just SKILL.md. A skill root may include references/, templates/, scripts/, and assets/. If the source skill has support files OR its SKILL.md contains relative links to them, DO NOT flatten only SKILL.md into <umbrella>/references/<old>.md. Choose one safe path instead: keep it as a standalone skill, OR fully merge by re-homing every needed support file into the umbrella's canonical directories AND rewriting the destination instructions to the new paths, OR archive the entire original skill package unchanged. Never leave demoted instructions pointing at files left behind under the old skill directory.\n4. Flag skills whose NAME is too narrow (contains a PR number, a feature codename, a specific error string, an 'audit'/'diagnosis'/'salvage' session artifact) \u2014 they almost always belong as a subsection or support file under a class-level umbrella.\n5. Iterate. After one consolidation round, scan the remaining set and look for the NEXT umbrella opportunity. Don't stop after 3 merges.\n\nYou are a NOMINATOR, not an executor: this channel has NO tools. Your single deliverable is the structured YAML block below. Never narrate actions you did not take (\"merged\", \"patched\", \"archived\") \u2014 you are proposing, and the deterministic engine executes only names from the candidate pool it gave you. (A future execution view would expose skill_manage; today it does not.)\n\n'keep' is a legitimate decision ONLY when the skill is already a class-level umbrella and none of the proposed merges would improve discoverability. 'This is narrow but distinct from its siblings' is NOT a reason to keep \u2014 it's a reason to move it under an umbrella as a subsection or support file.\n\nExpected output: real umbrella-ification. Process every obvious cluster. If you end the pass with obvious clusters still untouched, you stopped too early \u2014 go back and look at the clusters you left alone.\n\nKeep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.\n\nWhen done, write a human summary THEN the structured machine-readable block. The block is the contract: every skill you would move to .archive/ MUST appear in exactly one of the two lists. Return ONLY the YAML block after the summary \u2014 no post-block prose. Format EXACTLY:\n\n## Structured summary (required)\n```yaml\nconsolidations:\n  - from: <old-skill-name>\n    into: <umbrella-skill-name>\n    reason: <one short sentence \u2014 why merged, not just 'similar'>\nprunings:\n  - name: <skill-name>\n    reason: <one short sentence \u2014 why archived with no merge target>\n```\n\nEvery skill you would move to .archive/ MUST appear in exactly one of the two lists. If you consolidated X into umbrella Y (patched Y, wrote a references file to Y, or created Y with X's content absorbed), X goes under consolidations with into: Y. If you archived X with no absorption \u2014 truly stale, irrelevant, or obsolete \u2014 X goes under prunings. Leave a list empty (consolidations: []) if none. Do not omit the block. The block comes AFTER your human-readable summary of clusters processed, patches made, and decisions left alone.";
+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 ONLY skills loaded or read 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.";
+/**
+ * System-prompt guidance section (Hermes `SKILLS_GUIDANCE`, DSH-adapted).
+ * Registered as a system-prompt section by tool-skill-manage (it mounts
+ * exactly when `skill_manage` is available — the DSH analogue of Hermes'
+ * `if "skill_manage" in agent.valid_tool_names` condition). Instructs the
+ * model to save/repair skills on its own initiative.
+ */
+export declare const SKILLS_GUIDANCE = "Skills guidance:\n\u2022 After completing a complex task (5+ tool calls), fixing a tricky error, or discovering a non-trivial workflow, save the approach as a skill with skill_manage so you can reuse it next time.\n\u2022 When using a skill and finding it outdated, incomplete, or wrong, patch it immediately with skill_manage (action='patch') \u2014 don't wait to be asked. Skills that aren't maintained become liabilities.";
+/** Subagent-channel variant: same review policy, channel-limited deliverable (M-2). */
+export declare const SKILL_REVIEW_PLAN_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. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update.\n\nSignals to look for (any one of these warrants action):\n  \u2022 User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing.\n  \u2022 User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task.\n  \u2022 Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.\n  \u2022 A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.\n\nRead-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session \u2014 ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.\n\nPreference order \u2014 prefer the earliest action that fits, but do pick one when a signal above fired:\n  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.\n  2. UPDATE AN EXISTING UMBRELLA. If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.\n  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files \u2014 use the right directory per kind:\n     \u2022 references/<topic>.md \u2014 session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs.\n     \u2022 templates/<name>.<ext> \u2014 starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).\n     \u2022 scripts/<name>.<ext> \u2014 statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time).\n     Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists.\n  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong \u2014 fall back to (1), (2), or (3).\n\nUser-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson.\n\nIf you notice two existing skills that overlap, note it in your reply \u2014 the background curator handles consolidation at scale.\n\nTwo-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:\n  \u2022 PATTERN (reusable \u2014 symptom \u2192 mechanism \u2192 fix \u2192 verification, still valuable next session) belongs in the SKILL.md body.\n  \u2022 LOG (one-off \u2014 commit SHAs, npm/profile states, what this release changed, this session's process narrative) belongs in a references/ file, never the body. Body density IS reuse rate. Keep new entries tight: a pattern fits in 2-8 physical lines; prefer changing the current-state pointer over appending history.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.\n\nIf a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting 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. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.\n\nCHANNEL (subagent): this review channel mounts only the read-only `skill` tool \u2014 you have NO `skill_manage`, NO `memory`. Your deliverable is the structured JSON plan below (outputSchema). Describe the patches/creates you RECOMMEND in the plan; never narrate actions you took.";
+/** Subagent-channel variant of the combined review (M-2). */
+export declare const COMBINED_REVIEW_PLAN_PROMPT = "[Auto-review]\nReview the conversation above and update two things:\n\n**Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool.\n\n**Skills**: how to do this class of task. Be ACTIVE \u2014 most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries.\n\nSignals that warrant a skill update (any one is enough):\n  \u2022 User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' \u2014 embed the lesson in the skill that governs that task so the next session starts fixed.\n  \u2022 Non-trivial technique, fix, workaround, or debugging path emerged.\n  \u2022 A skill that was loaded or consulted turned out wrong, missing, or outdated \u2014 patch it now.\n\nRead-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session \u2014 ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.\n\nPreference order for skills \u2014 pick the earliest that fits:\n  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.\n  2. UPDATE AN EXISTING UMBRELLA. Patch it.\n  3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: references/<topic>.md for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; templates/<name>.<ext> for starter files meant to be copied and modified; scripts/<name>.<ext> for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them.\n  4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level \u2014 NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3).\n\nTwo-tier deposition discipline (DSH addition): classify before writing \u2014 PATTERN (symptom \u2192 mechanism \u2192 fix \u2192 verification) goes in the SKILL.md body; LOG (commit SHAs, npm/profile states, this release's change list, this session's narrative) goes in a references/ file. Body density IS reuse rate; a pattern fits in 2-8 physical lines.\n\nUser-preference embedding: when the user complains about how you handled a task, update the skill that governs that task \u2014 memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant.\n\nIf you notice overlapping existing skills, mention it \u2014 the background curator handles consolidation.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.\n\nIf a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill \u2014 never 'this tool does not work' as a standalone constraint.\n\nAct on whichever of the two dimensions 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.\n\nCHANNEL (subagent): this review channel mounts only the read-only `skill` tool \u2014 you have NO `skill_manage`, NO `memory`. Your deliverable is the structured JSON plan below (outputSchema). Describe the patches/creates you RECOMMEND in the plan; never narrate actions you took.";
+export declare function reviewPrompt(kind: 'memory' | 'skill' | 'combined', channel?: 'agent' | 'plan'): string;
 export interface PromptBundle {
     id: string;
     version: number;
@@ -12,5 +32,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. If the description contains a colon, wrap the whole value in double quotes.\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 \u2014 an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field 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/`.\n\nLearn workflow (when the user asks you to learn a reusable skill, or you decide to turn a source/request into one):\n1. Gather every source named (files, URLs, \"what we just did\", pasted notes) with the tools you already have \u2014 and treat prose after a source as authoring requirements, not noise.\n2. Apply every requirement and constraint from the request to the SKILL.md you author.\n3. Author exactly ONE SKILL.md and save it with `skill_manage` (action=create); non-trivial scripts go under `scripts/`.\n4. When done, tell the user the skill name, its category, and a one-line summary of what it captured.";
 //# sourceMappingURL=prompts.d.ts.map

package/lib/types/quality.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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[][];
+/**
+ * Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
+ * the curator prompt asks the model to identify "prefix clusters — skills
+ * sharing a first word or domain keyword"; the deterministic index supplies
+ * stable ground truth instead of letting the model infer clusters from the
+ * raw list. Key = first alphanumeric run of the lowercased name; groups with
+ * at least two members, largest first then alphabetical. Orientation-only:
+ * nomination authority stays with the LLM and the candidate-pool gates.
+ */
+export declare function computePrefixClusters(names: ReadonlyArray<string>): Array<{
+    key: string;
+    members: string[];
+}>;
+//# sourceMappingURL=quality.d.ts.map

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

@@ -7,11 +7,8 @@
  * 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';
+import type { EvolutionSkillMutatedEvent } from './events.ts';
 export interface SkillLimits {
     maxNameLength: number;
     maxDescriptionLength: number;
@@ -19,7 +16,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,7 +29,52 @@ 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;
+/**
+ * Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
+ * the APPROVAL surface treats every delegated subagent as the autonomous
+ * review channel, while the LIBRARY surface keeps the Hermes distinction -
+ * the review fork is 'background_review' (the pinned guard blocks its
+ * writes) and any other subagent is 'subagent' (agent-authored, not
+ * review-channel). `isReview` marks the caller as the background review
+ * pipeline itself. Single source: the two tools and the review executor all
+ * read this table instead of re-deriving it.
+ */
+export declare function resolveOrigins(headerOrigin: string | undefined, isReview?: boolean): {
+    approval: 'foreground' | 'background_review';
+    library: WriteOrigin;
+};
 export interface Frontmatter {
     name?: string;
     description?: string;
@@ -43,41 +84,132 @@ export declare function parseFrontmatter(content: string): {
     frontmatter: Frontmatter;
     body: string;
 } | null;
+/**
+ * Skill names referenced by a SKILL.md's `related_skills` frontmatter
+ * (B-line G3, rc.44): the single parsing source for the quality references
+ * factor and the learning-graph edges. The DSH frontmatter parser keeps the
+ * YAML value as a string (`"[a, b]"`), so names are scanned out of it; each
+ * must satisfy the skill-name shape and the referencing skill itself is
+ * excluded. Pure and deduplicated.
+ */
+export declare function relatedSkillNames(content: string, exclude?: string): string[];
 export declare function validateFrontmatter(content: string, expectedName?: string, limits?: SkillLimits): string | null;
+/** Hermes authoring quality bar for descriptions (the 60-char Rule). The
+ * platform's own index limit stays in `validateFrontmatter`; this bar is the
+ * target the authoring standard names, enforced as ADVISORY feedback. */
+export declare const AUTHORING_DESCRIPTION_BAR = 60;
+export interface AuthoringFeedback {
+    /** Frontmatter description length in characters (0 when absent). */
+    descriptionChars: number;
+    /** Whether the description exceeds the authoring bar (60) while still passing the platform limit. */
+    over60: boolean;
+    /** Whether the description contains a colon (the standard requires double-quote wrapping). */
+    hasColon: boolean;
+    /** Advice lines appended to mutation success messages. */
+    lines: string[];
+}
+/**
+ * Advisory authoring feedback (P0): evaluate frontmatter against the
+ * authoring bar WITHOUT changing platform validation semantics. The bar is
+ * the quality target, `validateFrontmatter`'s limits are the compatibility
+ * floor, and this bridge layer tells the model when its text would be
+ * truncated or route-poor instead of silently shipping it.
+ */
+export declare function authoringFeedback(frontmatter: Frontmatter): AuthoringFeedback;
 export declare class SkillLibrary {
     readonly root: string;
     readonly limits: SkillLimits;
     private readonly io;
-    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits);
+    private readonly onMutation;
+    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void);
+    /** Notify the mutation observer after a successful write; observers must never fail the mutation. */
+    private notifyMutation;
     list(): Promise<SkillSummary[]>;
-    read(name: string): Promise<string | null>;
-    writeProtection(name: string): Promise<string | null>;
-    deleteProtection(name: string): 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>;
+    read(rawName: string): Promise<string | null>;
+    /**
+  
+     * Single path-building choke point (rc.42 audit P2-5): every directory path
+  
+     * is built from the TRIMMED name, so a name that passes `badName` (which
+  
+     * trims before validating) can never mint a second, whitespace-padded
+  
+     * directory next to the real one. Callers keep passing raw user input.
+  
+     */
+    private dirOf;
+    /** Name-format guard shared by every path-building mutator/reader. */
+    private badName;
+    writeProtection(rawName: string, origin?: WriteOrigin): Promise<string | null>;
+    deleteProtection(rawName: string, options?: {
+        allowBundled?: boolean;
+    }): Promise<string | null>;
+    isManaged(rawName: string): Promise<boolean>;
+    /** Whether the skill carries the bundled marker (curator prune-builtins eligibility). */
+    isBundled(rawName: string): Promise<boolean>;
+    /** Whether the skill carries the pinned marker (the marker is the factual source; usage.pinned mirrors it). */
+    isPinned(rawName: string): Promise<boolean>;
+    /** Count non-empty support subdirectories (richness input for quality scoring). */
+    countSupportDirs(rawName: 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(rawName: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    patch(rawName: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
+    archive(rawName: 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[]): Promise<SkillActionResult>;
+    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): Promise<SkillActionResult>;
-    removeSupportFile(name: string, filePath: string): Promise<SkillActionResult>;
-    snapshotAll(reason?: string): Promise<string>;
+    restoreFromArchive(rawName: string): Promise<SkillActionResult>;
+    writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    removeSupportFile(rawName: 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); older ones are removed outright. */
+    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

@@ -1,19 +1,6 @@
 /**
- * Small crash-safe JSON state store for plugin-owned sidecar state.
- * Writes are atomic (temp + rename). Reads are synchronous for startup use.
+ * Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
+ * state (reports, activity store, feedback file, state-domain data).
  */
 export declare function evolutionHome(env?: NodeJS.ProcessEnv): string;
-export declare class JsonState<T> {
-    private readonly initial;
-    readonly path: string;
-    private value;
-    constructor(name: string, initial: T, env?: NodeJS.ProcessEnv);
-    private loadSync;
-    get(): T;
-    set(value: T): void;
-    update(mutator: (value: T) => void): void;
-    flush(): Promise<void>;
-    /** Merge-on-load helper for persisted maps/records. */
-    reload(): Promise<void>;
-}
 //# sourceMappingURL=state-store.d.ts.map

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

@@ -16,13 +16,63 @@ export interface UsageRecord {
     state: SkillState;
     pinned: boolean;
     archived_at: string | null;
-    quality_score?: number;
-    quality_warn?: boolean;
+    quality_score?: number | undefined;
+    quality_warn?: boolean | undefined;
 }
 export type UsageMap = Map<string, UsageRecord>;
 export declare function usageFile(root: string): string;
 export declare function emptyRecord(): UsageRecord;
+/**
+ * Field-level normalization for one sidecar record (rc.42 audit P2-3): the
+ * spread used to copy any junk through verbatim, so a corrupted file could
+ * carry `use_count: "3"` into the quality math and lifecycle comparisons as
+ * NaN. Every field falls back to its `emptyRecord()` baseline unless it has
+ * exactly the declared type; an invalid `created_at` anchors the age clock at
+ * now (first-sight defer semantics for a record whose age is unknowable).
+ * Timestamps additionally require a parseable date (N-3): `"not-a-date"`
+ * would otherwise survive the type check as Invalid Date.
+ * Pure — exported for unit tests; `loadUsage` is the production caller.
+ */
+export declare function normalizeUsageRecord(record: unknown): UsageRecord;
 export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<UsageMap>;
+/**
+ * Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
+ * the map parsed from the current on-disk state and may mutate it; the result
+ * is persisted inside the same transact so a second process sharing DSH_HOME
+ * cannot interleave its RMW and lose a counter update. Callers keep their own
+ * single-process serialize chain as the second layer.
+ */
+export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>): Promise<void>;
+/**
+ * Curator-owned usage fields (rc.67 K-2): the curator writes ONLY this set —
+ * lifecycle state, archive stamp, the six-factor quality pair, and the
+ * marker-mirrored pin flag. Counter and activity-stamp fields belong to the
+ * tool-telemetry side (skill-usage / tool-skill-manage), which bumps them
+ * through its own transact-backed RMW. A whole-record overwrite by either
+ * side would clobber the other side's concurrent increment, so cross-side
+ * folds copy this set only.
+ */
+export declare function applyCuratorFields(disk: UsageRecord, curated: UsageRecord): void;
+/** Copy only the lifecycle pair (state/archived_at) — see the ownership split
+ * rationale on {@link applyCuratorMetaFields}. */
+export declare function applyCuratorLifecycleFields(disk: UsageRecord, curated: UsageRecord): void;
+/**
+ * Copy the recomputed meta pair (quality_score/quality_warn + the
+ * marker-mirrored pin flag) — refreshed tree-wide each run by design, so a
+ * concurrent curator run's lifecycle changes are never reverted by them.
+ */
+export declare function applyCuratorMetaFields(disk: UsageRecord, curated: UsageRecord): void;
+/**
+ * Fold a curator run-start snapshot onto the current on-disk map (rc.67 K-2):
+ * each curated record is projected onto its disk peer by copying only the
+ * curator-owned fields, so a concurrent tool-side bump between snapshot and
+ * save survives. Records absent from the snapshot are left untouched; a
+ * curated record with no disk peer is seeded from the snapshot. `stateOwned`
+ * (rc.72 H-1) restricts the lifecycle pair to the names this run ACTUALLY
+ * transitioned — a concurrent curator run's archive/restore is never reverted
+ * by a stale snapshot; without it both pairs apply everywhere.
+ */
+export declare function foldCuratorFields(disk: UsageMap, curated: UsageMap, stateOwned?: ReadonlySet<string>): void;
 export declare function saveUsage(root: string, map: UsageMap, io?: EvolutionIoLike): Promise<void>;
 export declare function getRecord(map: UsageMap, name: string): UsageRecord;
 export declare function bumpView(map: UsageMap, name: string, when?: Date): void;
@@ -30,4 +80,21 @@ 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>;
+/**
+ * Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
+ * receives the set parsed from the current on-disk state and may mutate it;
+ * the result is persisted inside the same transact so a second process
+ * sharing DSH_HOME cannot interleave its RMW. Best-effort posture unchanged.
+ */
+export declare function updateSuppressedNames(root: string, io: EvolutionIoLike, task: (names: Set<string>) => void | Promise<void>): 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.9",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -32,13 +32,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
   }
 }