@lmzhen/dsh-evolution-core 0.1.0-rc.25 → 0.1.0-rc.27

package/lib/index.js

@@ -308,6 +308,50 @@ function parseCuratorNominations(text) {
 		consolidations: consolidations.filter((item) => valid(item.from) && valid(item.into))
 	};
 }
+/**
+* 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.
+*/
+function lifecycleCandidate(name, record, config, bundled) {
+	if (record.pinned) return false;
+	if (config.excludeSkillNames?.has(name)) return false;
+	if (config.suppressedNames?.has(name)) return false;
+	if (config.referencedSkillNames?.has(name)) return false;
+	if (!(record.created_by === "agent" || config.manageUnmanaged === true) && !(config.pruneBuiltins === true && bundled)) return false;
+	if (PROTECTED_BUILTIN_SKILLS.has(name)) return false;
+	if (record.state === "archived") return false;
+	return true;
+}
+/**
+* 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.
+*/
+function computeScopeView(usage, config) {
+	const managed = [];
+	const watched = [];
+	const exempted = [];
+	const protectedNames = [];
+	for (const [name, record] of usage) {
+		if (config.excludeSkillNames?.has(name) || config.referencedSkillNames?.has(name)) {
+			exempted.push(name);
+			continue;
+		}
+		const bundled = config.bundledNames?.has(name) === true;
+		if (record.pinned || bundled || config.suppressedNames?.has(name) === true) protectedNames.push(name);
+		if (lifecycleCandidate(name, record, config, bundled)) {
+			managed.push(name);
+			if (record.state === "stale" || record.quality_warn === true) watched.push(name);
+		}
+	}
+	return {
+		managed: managed.sort(),
+		watched: watched.sort(),
+		exempted: exempted.sort(),
+		protected: protectedNames.sort()
+	};
+}
 function daysSince(iso, created, now) {
 	return (now - new Date(iso ?? created).getTime()) / 864e5;
 }
@@ -319,14 +363,7 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 		markStale: []
 	};
 	for (const [name, record] of usage) {
-		if (record.pinned) continue;
-		if (config.excludeSkillNames?.has(name)) continue;
-		if (config.suppressedNames?.has(name)) continue;
-		if (config.referencedSkillNames?.has(name)) continue;
-		const bundled = config.bundledNames?.has(name) === true;
-		if (!(record.created_by === "agent" || config.manageUnmanaged === true) && !(config.pruneBuiltins === true && bundled)) continue;
-		if (PROTECTED_BUILTIN_SKILLS.has(name)) continue;
-		if (record.state === "archived") continue;
+		if (!lifecycleCandidate(name, record, config, config.bundledNames?.has(name) === true)) continue;
 		const age = daysSince(null, record.created_at, now.getTime());
 		if (record.use_count === 0 && age < config.staleAfterDays) continue;
 		const idle = daysSince(latestActivityAt(record), record.created_at, now.getTime());
@@ -533,6 +570,7 @@ Frontmatter:
 - author: always the literal value "Hermes". NEVER fill it from the environment, git config, or any identity you can probe.
 - platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.
 - metadata.hermes.tags: a few Capitalized, Relevant, Tags.
+- metadata.hermes.related_skills: [a, b] — name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).
 
 Body section order (omit only when empty):
 1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.
@@ -1685,6 +1723,11 @@ var SkillLibrary = class {
 		const dir = skillDir(this.root, name);
 		return await this.io.exists(markerPath(dir, "bundled"));
 	}
+	/** Whether the skill carries the pinned marker (the marker is the factual source; usage.pinned mirrors it). */
+	async isPinned(name) {
+		const dir = skillDir(this.root, name);
+		return await this.io.exists(markerPath(dir, "pinned"));
+	}
 	/** Count non-empty support subdirectories (richness input for quality scoring). */
 	async countSupportDirs(name) {
 		const dir = skillDir(this.root, name);
@@ -1720,6 +1763,48 @@ var SkillLibrary = class {
 	async listMutations() {
 		return await loadMutations(this.root, this.io);
 	}
+	/**
+	* 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.
+	*/
+	async setPinned(name, pinned, origin = "foreground") {
+		const normalized = name.trim();
+		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return {
+			ok: false,
+			message: `Invalid skill name "${normalized}". Use lowercase letters, digits, and hyphens (<= ${this.limits.maxNameLength}).`
+		};
+		if (origin === "background_review") return {
+			ok: false,
+			message: "Only the foreground (user or the main agent) may pin or unpin skills."
+		};
+		const dir = skillDir(this.root, normalized);
+		const marker = markerPath(dir, "pinned");
+		const existing = await this.io.exists(marker);
+		if (pinned && existing) return {
+			ok: true,
+			message: `Skill "${normalized}" is already pinned.`,
+			path: dir
+		};
+		if (!pinned && !existing) return {
+			ok: true,
+			message: `Skill "${normalized}" is not pinned; nothing to do.`,
+			path: dir
+		};
+		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
+			ok: false,
+			message: `Skill "${normalized}" not found.`
+		};
+		if (pinned) await this.io.writeText(marker, "");
+		else await this.io.remove(marker);
+		await this.audit(normalized, pinned ? "pin" : "unpin", null, null, pinned ? "pinned" : "unpinned");
+		return {
+			ok: true,
+			message: pinned ? `Skill "${normalized}" pinned: protected from deletion, background review, and the lifecycle.` : `Skill "${normalized}" unpinned.`,
+			path: dir
+		};
+	}
 	async create(name, content, origin) {
 		const normalized = name.trim();
 		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return {
@@ -2185,4 +2270,4 @@ var JsonState = class JsonState {
 	}
 };
 //#endregion
-export { COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };
+export { COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, computeScopeView, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, lifecycleCandidate, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };

package/lib/types/curator.d.ts

@@ -2,7 +2,7 @@
  * Deterministic skill curator: active → stale → archived transitions.
  * Pure function; 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;
@@ -87,5 +87,27 @@ export interface CuratorNominations {
  * 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[];
+    /** 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.
+ */
+export declare function computeScopeView(usage: UsageMap, config: CuratorConfig): ScopeView;
 export declare function computeLifecycleTransitions(usage: UsageMap, config: CuratorConfig, now?: Date): CuratorResult;
 //# sourceMappingURL=curator.d.ts.map

package/lib/types/prompts.d.ts

@@ -20,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/skill-store.d.ts

@@ -64,12 +64,21 @@ export declare class SkillLibrary {
     isManaged(name: string): Promise<boolean>;
     /** 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: 'foreground' | 'background_review'): 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>;

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.25",
+  "version": "0.1.0-rc.27",
   "publishConfig": {
     "access": "public"
   },