@lmzhen/dsh-evolution-core 0.1.0-rc.26 → 0.1.0-rc.28

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());
@@ -1659,8 +1696,15 @@ var SkillLibrary = class {
 		return summaries;
 	}
 	async read(name) {
+		if (this.badName(name) !== null) return null;
 		return this.io.readText(join(skillDir(this.root, name), "SKILL.md"));
 	}
+	/** Name-format guard shared by every path-building mutator/reader. */
+	badName(name) {
+		const normalized = name.trim();
+		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return `Invalid skill name "${normalized}". Use lowercase letters, digits, and hyphens (<= ${this.limits.maxNameLength}).`;
+		return null;
+	}
 	async writeProtection(name, origin = "foreground") {
 		const dir = skillDir(this.root, name);
 		for (const marker of ["bundled", "hub-installed"]) if (await this.io.exists(markerPath(dir, marker))) return marker;
@@ -1683,11 +1727,19 @@ var SkillLibrary = class {
 	}
 	/** Whether the skill carries the bundled marker (curator prune-builtins eligibility). */
 	async isBundled(name) {
+		if (this.badName(name) !== null) return false;
 		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) {
+		if (this.badName(name) !== null) return false;
+		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) {
+		if (this.badName(name) !== null) return 0;
 		const dir = skillDir(this.root, name);
 		let entries;
 		try {
@@ -1721,6 +1773,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 {
@@ -1752,6 +1846,11 @@ var SkillLibrary = class {
 		};
 	}
 	async update(name, content, origin = "foreground") {
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
 		const dir = skillDir(this.root, name);
 		const md = await this.io.readText(join(dir, "SKILL.md"));
 		if (!md) return {
@@ -1782,6 +1881,11 @@ var SkillLibrary = class {
 		};
 	}
 	async patch(name, oldString, newString, filePath = "", replaceAll = false, origin = "foreground") {
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
 		const dir = skillDir(this.root, name);
 		const skillMd = join(dir, "SKILL.md");
 		if (!await this.io.exists(skillMd)) return {
@@ -1843,6 +1947,11 @@ var SkillLibrary = class {
 		};
 	}
 	async archive(name, options = {}) {
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
 		const dir = skillDir(this.root, name);
 		const md = await this.io.readText(join(dir, "SKILL.md"));
 		if (!md) return {
@@ -2001,6 +2110,11 @@ var SkillLibrary = class {
 		};
 	}
 	async writeSupportFile(name, filePath, content, origin = "foreground") {
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
 		const dir = skillDir(this.root, name);
 		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
 			ok: false,
@@ -2036,6 +2150,11 @@ var SkillLibrary = class {
 		};
 	}
 	async removeSupportFile(name, filePath, origin = "foreground") {
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
 		const dir = skillDir(this.root, name);
 		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
 			ok: false,
@@ -2186,4 +2305,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/skill-store.d.ts

@@ -57,6 +57,8 @@ export declare class SkillLibrary {
     constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits);
     list(): Promise<SkillSummary[]>;
     read(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;
@@ -64,12 +66,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.26",
+  "version": "0.1.0-rc.28",
   "publishConfig": {
     "access": "public"
   },