sneakoscope 0.7.24 → 0.7.25

package/README.md

@@ -95,7 +95,7 @@ sks bootstrap
 
 `sks` commands work even when no project root is present. Project-aware commands use the nearest `.sneakoscope`, `.dcodex`, or `.git` root; if none exists, SKS uses a per-user global runtime root. `sks bootstrap` still initializes the current project when you want project-local hooks, skills, and TriWiki state.
 
-Project setup writes shared `.gitignore` entries for generated SKS files: `.sneakoscope/`, `.codex/`, `.agents/`, and managed `AGENTS.md`. Use `sks setup --local-only` when you want those excludes kept only in `.git/info/exclude`.
+Project setup writes shared `.gitignore` entries for generated SKS files: `.sneakoscope/`, `.codex/`, `.agents/`, and managed `AGENTS.md`. Setup, doctor repair, and npm postinstall refreshes also compare the previous SKS generated-file manifest with the current package templates and prune stale SKS-generated legacy skills or agent files while preserving user-owned custom skills. Use `sks setup --local-only` when you want those excludes kept only in `.git/info/exclude`.
 
 During npm postinstall, SKS also installs generated Codex App skills and tries the official getdesign Codex skill command, `skills add MohtashamMurshid/getdesign`, when the `skills` CLI is available. If that CLI is missing, setup still installs the generated `getdesign-reference` skill. Design work still flows through one authority: `design.md`. When `design.md` is missing, `docs/Design-Sys-Prompt.md` is the builder prompt and getdesign plus curated DESIGN.md examples such as [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) are inputs to fuse into that SSOT or into route-local `$PPT` style tokens.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.7.24",
+  "version": "0.7.25",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Goal, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",

package/src/cli/install-helpers.mjs

@@ -186,7 +186,14 @@ export async function ensureGlobalCodexSkillsDuringInstall(opts = {}) {
   try {
     const install = await installSkills(home);
     const skills = await checkRequiredSkills(home, root);
-    return { status: skills.ok ? 'installed' : 'partial', root, installed_count: install.installed_skills.length, removed_aliases: install.removed_agent_skill_aliases, missing_skills: skills.missing };
+    return {
+      status: skills.ok ? 'installed' : 'partial',
+      root,
+      installed_count: install.installed_skills.length,
+      removed_aliases: install.removed_agent_skill_aliases,
+      removed_stale_generated_skills: install.removed_stale_generated_skills,
+      missing_skills: skills.missing
+    };
   } catch (err) {
     return { status: 'failed', root, error: err.message };
   }

package/src/cli/main.mjs

@@ -1396,11 +1396,12 @@ async function doctor(args) {
   let conflictScan = await scanHarnessConflicts(root);
   let repairApplied = false;
   let globalSkillsRepair = null;
+  let projectRepair = null;
   const globalCommand = await globalSksCommand();
   if (flag(args, '--fix') && !conflictScan.hard_block) {
     const existingManifest = await readJson(path.join(root, '.sneakoscope', 'manifest.json'), null);
     const fixScope = requestedScope || normalizeInstallScope(existingManifest?.installation?.scope || 'global');
-    await initProject(root, { installScope: fixScope, globalCommand, localOnly: flag(args, '--local-only') || Boolean(existingManifest?.git?.local_only), force: true, repair: true });
+    projectRepair = await initProject(root, { installScope: fixScope, globalCommand, localOnly: flag(args, '--local-only') || Boolean(existingManifest?.git?.local_only), force: true, repair: true });
     if (!flag(args, '--local-only')) globalSkillsRepair = await ensureGlobalCodexSkillsDuringInstall({ force: true });
     repairApplied = true;
     conflictScan = await scanHarnessConflicts(root);
@@ -1427,7 +1428,7 @@ async function doctor(args) {
   const result = {
     node: { ok: nodeOk, version: process.version }, root, codex, rust,
     install,
-    repair: { applied: repairApplied, global_skills: globalSkillsRepair, blocked_by_other_harness: flag(args, '--fix') && conflictScan.hard_block },
+    repair: { applied: repairApplied, project: projectRepair, global_skills: globalSkillsRepair, blocked_by_other_harness: flag(args, '--fix') && conflictScan.hard_block },
     harness_conflicts: {
       ok: conflictScan.ok,
       hard_block: conflictScan.hard_block,
@@ -1743,6 +1744,26 @@ async function selftest() {
   await initProject(repairTmp, { installScope: 'project', localOnly: true });
   await writeTextAtomic(path.join(repairTmp, '.agents', 'skills', 'team', 'SKILL.md'), 'tampered\n');
   await writeTextAtomic(path.join(repairTmp, '.agents', 'skills', 'agent-team', 'SKILL.md'), '---\nname: agent-team\ndescription: Fallback Codex App picker alias for $Team.\n---\n');
+  await ensureDir(path.join(repairTmp, '.agents', 'skills', 'stale-sks-generated'));
+  await writeTextAtomic(path.join(repairTmp, '.agents', 'skills', 'stale-sks-generated', 'SKILL.md'), '---\nname: stale-sks-generated\ndescription: Old SKS generated skill that should disappear on update.\n---\n');
+  await writeJsonAtomic(path.join(repairTmp, '.agents', 'skills', '.sks-generated.json'), {
+    schema_version: 1,
+    generated_by: 'sneakoscope',
+    version: '0.0.1',
+    skills: ['team', 'stale-sks-generated'],
+    files: ['.agents/skills/team/SKILL.md', '.agents/skills/stale-sks-generated/SKILL.md']
+  });
+  const staleCodexAgentRel = '.codex/agents/stale-generated.toml';
+  await writeTextAtomic(path.join(repairTmp, staleCodexAgentRel), 'name = "stale_generated"\n');
+  const staleManifest = await readJson(path.join(repairTmp, '.sneakoscope', 'manifest.json'));
+  staleManifest.version = '0.0.1';
+  staleManifest.generated_files = {
+    schema_version: 1,
+    generated_by: 'sneakoscope',
+    prune_policy: 'remove_previous_sks_generated_paths_absent_from_current_manifest',
+    files: [...(staleManifest.generated_files?.files || []), '.agents/skills/stale-sks-generated/SKILL.md', staleCodexAgentRel]
+  };
+  await writeJsonAtomic(path.join(repairTmp, '.sneakoscope', 'manifest.json'), staleManifest);
   await ensureDir(path.join(repairTmp, '.agents', 'skills', 'custom-keep'));
   await writeTextAtomic(path.join(repairTmp, '.agents', 'skills', 'custom-keep', 'SKILL.md'), '---\nname: custom-keep\ndescription: User custom skill, not generated by SKS.\n---\n');
   await writeTextAtomic(path.join(repairTmp, '.codex', 'skills', 'team', 'SKILL.md'), 'legacy mirror\n');
@@ -1765,6 +1786,11 @@ async function selftest() {
   const repairedTeamSkill = await safeReadText(path.join(repairTmp, '.agents', 'skills', 'team', 'SKILL.md'));
   if (!repairedTeamSkill.includes('SKS Team orchestration') || repairedTeamSkill.includes('tampered')) throw new Error('selftest failed: doctor repair did not regenerate team skill');
   if (await exists(path.join(repairTmp, '.agents', 'skills', 'agent-team', 'SKILL.md'))) throw new Error('selftest failed: doctor repair did not remove deprecated agent-team alias skill');
+  if (await exists(path.join(repairTmp, '.agents', 'skills', 'stale-sks-generated', 'SKILL.md'))) throw new Error('selftest failed: doctor repair did not prune stale generated skill from previous SKS manifest');
+  if (await exists(path.join(repairTmp, staleCodexAgentRel))) throw new Error('selftest failed: doctor repair did not prune stale generated agent file from previous SKS manifest');
+  if (!doctorRepairJson.repair?.project?.skill_install?.removed_stale_generated_skills?.includes('.agents/skills/stale-sks-generated')) throw new Error('selftest failed: doctor repair did not report stale generated skill pruning');
+  const generatedCleanupReport = doctorRepairJson.repair?.project?.generated_cleanup || {};
+  if (![...(generatedCleanupReport.pruned || []), ...(generatedCleanupReport.already_absent || [])].includes(staleCodexAgentRel)) throw new Error('selftest failed: doctor repair did not report stale generated file pruning');
   if (!(await exists(path.join(repairTmp, '.agents', 'skills', 'custom-keep', 'SKILL.md')))) throw new Error('selftest failed: doctor repair removed a user-owned custom skill');
   if (await exists(path.join(repairTmp, '.codex', 'skills', 'team', 'SKILL.md'))) throw new Error('selftest failed: doctor repair did not remove legacy .codex/skills');
   const repairedQuickReference = await safeReadText(path.join(repairTmp, '.codex', 'SNEAKOSCOPE.md'));

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.7.24';
+export const PACKAGE_VERSION = '0.7.25';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/init.mjs

@@ -11,6 +11,8 @@ import { SKILL_DREAM_POLICY, skillDreamPolicyText } from './skill-forge.mjs';
 
 const REFLECTION_MEMORY_PATH = '.sneakoscope/memory/q2_facts/post-route-reflection.md';
 const SKS_GENERATED_GIT_PATTERNS = ['.sneakoscope/', '.codex/', '.agents/', 'AGENTS.md'];
+const SKS_SKILL_MANIFEST_FILE = '.sks-generated.json';
+const GENERATED_PRUNE_POLICY = 'remove_previous_sks_generated_paths_absent_from_current_manifest';
 
 function reflectionInstructionText(commandPrefix = 'sks') {
   return `Post-route reflection: full routes load \`reflection\` after work/tests and before final; DFix/Answer/Help/Wiki/SKS discovery are exempt. Write reflection.md; record only real misses/gaps, or no_issue_acknowledged. For lessons, append TriWiki claim rows to ${REFLECTION_MEMORY_PATH}. Run "${commandPrefix} wiki refresh" or pack, validate, then pass reflection-gate.json.`;
@@ -101,6 +103,8 @@ export async function initProject(root, opts = {}) {
   const requestedHookCommandPrefix = opts.hookCommandPrefix || sksCommandPrefix(installScope, { globalCommand: opts.globalCommand });
   const hookCommandPrefix = sourceProject ? 'node ./bin/sks.mjs' : requestedHookCommandPrefix;
   const sine = path.join(root, '.sneakoscope');
+  const manifestPath = path.join(sine, 'manifest.json');
+  const previousManifest = await readJson(manifestPath, null);
   if (opts.repair) {
     const repair = await repairSksGeneratedArtifacts(root, { resetState: Boolean(opts.resetState) });
     if (repair.removed.length) created.push(`repaired generated SKS files (${repair.removed.length})`);
@@ -114,7 +118,7 @@ export async function initProject(root, opts = {}) {
   if (localExclude?.path) created.push(`${path.relative(root, localExclude.path)} local-only excludes`);
   if (sharedIgnore?.changed) created.push(`${path.relative(root, sharedIgnore.path)} SKS generated files ignore`);
 
-  await writeJsonAtomic(path.join(sine, 'manifest.json'), {
+  const manifest = {
     package: 'sneakoscope',
     version: PACKAGE_VERSION,
     initialized_at: nowIso(),
@@ -197,7 +201,8 @@ export async function initProject(root, opts = {}) {
     },
     database_safety: 'destructive_db_operations_denied_always',
     gx_renderer: 'deterministic_svg_html'
-  });
+  };
+  await writeJsonAtomic(manifestPath, manifest);
   created.push('.sneakoscope/manifest.json');
 
   const dbSafetyPath = path.join(sine, 'db-safety.json');
@@ -467,16 +472,36 @@ policy = "Deny destructive database operations, credential exfiltration, persist
 
   const skillInstall = await installSkills(root);
   created.push('.agents/skills/*');
+  if (skillInstall.removed_stale_generated_skills.length) created.push(`stale generated skills removed (${skillInstall.removed_stale_generated_skills.length})`);
+  if (skillInstall.removed_agent_skill_aliases.length) created.push(`deprecated generated skill aliases removed (${skillInstall.removed_agent_skill_aliases.length})`);
   if (skillInstall.removed_codex_skill_mirrors.length) created.push(`.codex/skills generated mirrors removed (${skillInstall.removed_codex_skill_mirrors.length})`);
-  await installCodexAgents(root);
+  const agentInstall = await installCodexAgents(root);
   created.push('.codex/agents/*');
+  const generatedFiles = currentGeneratedFileInventory(skillInstall, agentInstall);
+  const generatedCleanup = await pruneStaleGeneratedFiles(root, previousManifest, generatedFiles);
+  if (generatedCleanup.pruned.length) created.push(`stale generated files pruned (${generatedCleanup.pruned.length})`);
+  manifest.generated_files = {
+    schema_version: 1,
+    generated_by: 'sneakoscope',
+    prune_policy: GENERATED_PRUNE_POLICY,
+    files: generatedFiles
+  };
+  manifest.generated_cleanup = {
+    schema_version: 1,
+    last_run_at: nowIso(),
+    previous_version: previousManifest?.version || null,
+    current_version: PACKAGE_VERSION,
+    pruned: generatedCleanup.pruned,
+    already_absent: generatedCleanup.already_absent || []
+  };
+  await writeJsonAtomic(manifestPath, manifest);
   await writeHarnessGuardPolicy(root);
   created.push('.sneakoscope/harness-guard.json');
   const versionHookCommand = sourceProject ? 'node ./bin/sks.mjs' : hookCommandPrefix;
   const versionHook = await installVersionGitHook(root, versionHookCommand);
   if (versionHook.installed) created.push('.git/hooks/pre-commit SKS version guard');
   else created.push(`version guard skipped (${versionHook.reason})`);
-  return { created };
+  return { created, generated_cleanup: generatedCleanup, skill_install: skillInstall };
 }
 
 async function ensureSharedGitIgnore(root) {
@@ -601,13 +626,57 @@ export async function installSkills(root) {
     await writeSkillMetadata(dir, name);
   }
   const skillNames = Object.keys(skills);
+  const removedStaleGeneratedSkills = await removeStaleGeneratedSkillsFromManifest(root, skillNames);
+  await writeGeneratedSkillManifest(root, skillNames);
   return {
     installed_skills: skillNames,
+    generated_files: generatedSkillFiles(skillNames),
+    removed_stale_generated_skills: removedStaleGeneratedSkills,
     removed_agent_skill_aliases: await removeGeneratedAgentSkillAliases(root, skillNames),
     removed_codex_skill_mirrors: await removeGeneratedCodexSkillMirrors(root, skillNames)
   };
 }
 
+function generatedSkillFiles(skillNames) {
+  return skillNames.flatMap((name) => [
+    `.agents/skills/${name}/SKILL.md`,
+    `.agents/skills/${name}/agents/openai.yaml`
+  ]).sort();
+}
+
+function generatedSkillManifestPath(root) {
+  return path.join(root, '.agents', 'skills', SKS_SKILL_MANIFEST_FILE);
+}
+
+async function writeGeneratedSkillManifest(root, skillNames) {
+  const manifestPath = generatedSkillManifestPath(root);
+  await writeJsonAtomic(manifestPath, {
+    schema_version: 1,
+    generated_by: 'sneakoscope',
+    version: PACKAGE_VERSION,
+    prune_policy: GENERATED_PRUNE_POLICY,
+    skills: [...skillNames].sort(),
+    files: generatedSkillFiles(skillNames)
+  });
+}
+
+async function removeStaleGeneratedSkillsFromManifest(root, skillNames) {
+  const previous = await readJson(generatedSkillManifestPath(root), null);
+  const previousSkills = Array.isArray(previous?.skills) ? previous.skills : [];
+  if (!previousSkills.length) return [];
+  const current = new Set(skillNames);
+  const removed = [];
+  for (const name of previousSkills) {
+    const skillName = String(name || '').trim();
+    if (!skillName || current.has(skillName) || !/^[a-z0-9-]+$/.test(skillName)) continue;
+    const dir = path.join(root, '.agents', 'skills', skillName);
+    if (!(await exists(dir))) continue;
+    await fsp.rm(dir, { recursive: true, force: true });
+    removed.push(path.relative(root, dir));
+  }
+  return removed.sort();
+}
+
 function enrichSkillContent(name, content) {
   if (!['sks', 'answer', 'wiki', 'team', 'qa-loop', 'ppt', 'computer-use', 'computer-use-fast', 'cu', 'goal', 'research', 'autoresearch', 'db', 'gx', 'reflection', 'prompt-pipeline', 'pipeline-runner', 'context7-docs', 'turbo-context-pack', 'hproof-evidence-bind'].includes(name)) return content;
   const text = String(content || '').trimEnd();
@@ -704,4 +773,89 @@ async function installCodexAgents(root) {
   for (const [file, content] of Object.entries(agents)) {
     await writeTextAtomic(path.join(dir, file), content);
   }
+  return {
+    installed_agents: Object.keys(agents),
+    generated_files: Object.keys(agents).map((file) => `.codex/agents/${file}`).sort()
+  };
+}
+
+function currentGeneratedFileInventory(skillInstall = {}, agentInstall = {}) {
+  return Array.from(new Set([
+    '.codex/config.toml',
+    '.codex/SNEAKOSCOPE.md',
+    '.codex/hooks.json',
+    '.sneakoscope/harness-guard.json',
+    '.sneakoscope/db-safety.json',
+    '.sneakoscope/policy.json',
+    '.agents/skills/.sks-generated.json',
+    ...(Array.isArray(skillInstall.generated_files) ? skillInstall.generated_files : []),
+    ...(Array.isArray(agentInstall.generated_files) ? agentInstall.generated_files : [])
+  ])).sort();
+}
+
+async function pruneStaleGeneratedFiles(root, previousManifest, currentFiles) {
+  const previousFiles = Array.isArray(previousManifest?.generated_files?.files) ? previousManifest.generated_files.files : [];
+  if (!previousFiles.length) return { pruned: [] };
+  const current = new Set(currentFiles);
+  const pruned = [];
+  const already_absent = [];
+  for (const rel of previousFiles) {
+    const relPath = normalizeGeneratedRelPath(rel);
+    if (!relPath || current.has(relPath) || !isPrunableGeneratedPath(relPath)) continue;
+    const removed = await removeGeneratedRelPath(root, relPath);
+    if (removed) pruned.push(removed);
+    else already_absent.push(relPath);
+  }
+  return { pruned: pruned.sort(), already_absent: already_absent.sort() };
+}
+
+function normalizeGeneratedRelPath(value) {
+  const rel = String(value || '').trim().replaceAll('\\', '/');
+  if (!rel || rel.startsWith('/') || rel.includes('\0')) return null;
+  if (rel.split('/').some((part) => part === '..')) return null;
+  return rel;
+}
+
+function isPrunableGeneratedPath(rel) {
+  if (rel.startsWith('.agents/skills/')) return true;
+  if (rel.startsWith('.codex/agents/')) return true;
+  if (rel.startsWith('.codex/skills/')) return true;
+  return new Set([
+    '.codex/config.toml',
+    '.codex/SNEAKOSCOPE.md',
+    '.codex/hooks.json',
+    '.sneakoscope/harness-guard.json',
+    '.sneakoscope/db-safety.json',
+    '.sneakoscope/policy.json'
+  ]).has(rel);
+}
+
+async function removeGeneratedRelPath(root, rel) {
+  const absRoot = path.resolve(root);
+  const abs = path.resolve(absRoot, rel);
+  if (abs !== absRoot && !abs.startsWith(`${absRoot}${path.sep}`)) return null;
+  if (!(await exists(abs))) return null;
+  await fsp.rm(abs, { recursive: true, force: true });
+  await removeEmptyGeneratedParents(root, rel);
+  return rel;
+}
+
+async function removeEmptyGeneratedParents(root, rel) {
+  const parts = rel.split('/');
+  if (parts.length <= 1) return;
+  const stopDirs = new Set([
+    path.resolve(root, '.agents', 'skills'),
+    path.resolve(root, '.codex', 'agents'),
+    path.resolve(root, '.codex', 'skills'),
+    path.resolve(root, '.codex'),
+    path.resolve(root, '.sneakoscope')
+  ]);
+  let dir = path.resolve(root, ...parts.slice(0, -1));
+  while (!stopDirs.has(dir) && dir.startsWith(path.resolve(root))) {
+    await removeDirIfEmpty(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (rel.startsWith('.codex/skills/')) await removeDirIfEmpty(path.join(root, '.codex', 'skills'));
 }