skillwiki 0.9.22 → 0.9.23

package/dist/cli.js

@@ -3525,6 +3525,7 @@ function buildCliSurface() {
   memoryCmd2.command("topics").option("--project <slug>").option("--limit <n>").option("--wiki <name>");
   memoryCmd2.command("index").requiredOption("--project <slug>").option("--check").option("--if-stale").option("--wiki <name>");
   memoryCmd2.command("recall").requiredOption("--project <slug>").requiredOption("--topic <slug>").option("--scope <scope>").option("--limit <n>").option("--wiki <name>");
+  memoryCmd2.command("review").requiredOption("--project <slug>").option("--dry-run").option("--wiki <name>");
   memoryCmd2.command("import").requiredOption("--from <path>").requiredOption("--project <slug>").option("--dry-run").option("--apply").option("--max-bytes <n>").option("--wiki <name>");
   const fleetCmd2 = program2.commands.find((c) => c.name() === "fleet");
   fleetCmd2.command("validate");
@@ -9138,6 +9139,41 @@ async function runMemoryRecall(input) {
     })
   };
 }
+async function runMemoryReview(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const state = await buildMemoryIndexState(scan.data.allMarkdown, input.project);
+  const checked = await checkMemoryIndex(input.vault, input.project, state);
+  if (!checked.ok) {
+    return {
+      exitCode: checked.error.exitCode,
+      result: checked.error.result
+    };
+  }
+  const findings = buildMemoryReviewFindings({
+    project: input.project,
+    status: checked.data,
+    indexState: state,
+    reviewPages: state.reviewPages
+  });
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      project: input.project,
+      generated_at: generatedAt,
+      cache: {
+        present: checked.data.cache_present,
+        ...checked.data.generated_at ? { generated_at: checked.data.generated_at } : {},
+        stale: checked.data.stale,
+        source_hash_mismatches: checked.data.drift.changed_sources
+      },
+      findings,
+      files_written: [],
+      humanHint: renderMemoryReviewHint(input.project, checked.data, findings)
+    })
+  };
+}
 async function runMemoryImport(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -9197,14 +9233,18 @@ async function buildMemoryIndexState(pages, project) {
   const warnings = [];
   const sourcePages = dedupePages(pages);
   const sources = [];
+  const reviewPages = [];
   for (const page of sourcePages) {
-    const source = await readMemorySource(page, project, warnings);
-    if (source) sources.push(source);
+    const memoryPage = await readMemoryPage(page, project, warnings);
+    if (!memoryPage) continue;
+    sources.push(memoryPage.source);
+    if (memoryPage.reviewPage) reviewPages.push(memoryPage.reviewPage);
   }
   return {
     sources,
     topics: buildTopics(project, sources),
-    warnings
+    warnings,
+    reviewPages
   };
 }
 async function checkMemoryIndex(vault, project, current) {
@@ -9290,6 +9330,175 @@ function emptyMemoryIndexDrift() {
     changed_sources: []
   };
 }
+async function readMemoryPage(page, project, warnings) {
+  const text = await readPage(page);
+  const fm = extractFrontmatter(text);
+  if (!fm.ok) return null;
+  const rawTopics = typeof fm.data.memory_topics === "string" ? [fm.data.memory_topics] : stringArray(fm.data.memory_topics);
+  if (rawTopics.length === 0) return null;
+  const topics = normalizeMemoryTopics(fm.data.memory_topics, page.relPath, warnings);
+  if (topics.length === 0) return null;
+  const scope = stringField2(fm.data.memory_scope);
+  const projects = memoryProjects(page.relPath, fm.data);
+  if (!projects.includes(project) && scope !== "global" && scope !== "cross-agent") return null;
+  const privacy = stringField2(fm.data.memory_privacy) || "local";
+  if (privacy === "secret-blocked") {
+    warnings.push(`${page.relPath}: skipped secret-blocked memory`);
+    return null;
+  }
+  const status = stringField2(fm.data.memory_status) || "active";
+  if (status === "archived" || status === "rejected") return null;
+  const metadataGaps = [];
+  if (!scope) metadataGaps.push("memory_scope");
+  if (!stringField2(fm.data.memory_policy)) metadataGaps.push("memory_policy");
+  if (!stringField2(fm.data.memory_privacy)) metadataGaps.push("memory_privacy");
+  if (!stringField2(fm.data.memory_status)) metadataGaps.push("memory_status");
+  if (!stringField2(fm.data.last_seen) && !stringField2(fm.data.updated) && !stringField2(fm.data.ingested)) {
+    metadataGaps.push("freshness");
+  }
+  const split = splitFrontmatter(text);
+  const body = split.ok ? split.data.body : text;
+  const updated = stringField2(fm.data.last_seen) || stringField2(fm.data.updated) || stringField2(fm.data.ingested) || dateFromPath2(page.relPath);
+  const title = stringField2(fm.data.title) || page.relPath.split("/").pop()?.replace(/\.md$/, "") || page.relPath;
+  return {
+    source: {
+      path: page.relPath,
+      title,
+      summary: summarize2(body),
+      updated,
+      hash: createHash8("sha256").update(Buffer.from(body, "utf8")).digest("hex"),
+      topics,
+      project,
+      ...stringField2(fm.data.memory_kind) ? { memory_kind: stringField2(fm.data.memory_kind) } : {},
+      ...scope ? { memory_scope: scope } : {},
+      ...stringField2(fm.data.memory_policy) ? { memory_policy: stringField2(fm.data.memory_policy) } : {},
+      memory_privacy: privacy,
+      memory_status: status
+    },
+    ...metadataGaps.length > 0 ? {
+      reviewPage: {
+        path: page.relPath,
+        metadataGaps
+      }
+    } : {}
+  };
+}
+function buildMemoryReviewFindings(input) {
+  const findings = [];
+  if (!input.status.cache_present) {
+    findings.push({
+      id: `cache_missing:${input.project}`,
+      severity: "warn",
+      kind: "cache_missing",
+      message: `memory cache for ${input.project} is missing`,
+      suggested_action: `Run skillwiki memory index --project ${input.project} to build the local cache.`
+    });
+  } else if (input.status.stale) {
+    findings.push({
+      id: `cache_stale:${input.project}`,
+      severity: "warn",
+      kind: "cache_stale",
+      message: `memory cache for ${input.project} is stale: ${input.status.drift.missing_sources.length} missing, ${input.status.drift.removed_sources.length} removed, ${input.status.drift.changed_sources.length} changed source(s)`,
+      suggested_action: `Run skillwiki memory index --project ${input.project} or --if-stale to refresh the local cache.`
+    });
+  }
+  for (const path of input.status.drift.changed_sources) {
+    findings.push({
+      id: `source_hash_drift:${path}`,
+      severity: "warn",
+      kind: "source_hash_drift",
+      path,
+      message: `${path} changed since the last cache build`,
+      suggested_action: `Refresh the cache for ${input.project} and review whether the source summary still matches.`
+    });
+  }
+  for (const warning of input.indexState.warnings) {
+    const parsed = parseInvalidTopicWarning(warning);
+    if (!parsed) continue;
+    findings.push({
+      id: `invalid_topic_slug:${parsed.path}:${parsed.topic}`,
+      severity: "warn",
+      kind: "invalid_topic_slug",
+      path: parsed.path,
+      topic: parsed.topic,
+      message: `${parsed.path} declares invalid memory topic slug ${parsed.topic}`,
+      suggested_action: "Normalize the topic slug to lowercase kebab-case so memory index and review can include it."
+    });
+  }
+  for (const page of input.reviewPages) {
+    if (page.metadataGaps.length === 0) continue;
+    findings.push({
+      id: `metadata_gap:${page.path}`,
+      severity: "warn",
+      kind: "metadata_gap",
+      path: page.path,
+      message: `${page.path} is missing explicit memory metadata: ${page.metadataGaps.join(", ")}`,
+      suggested_action: "Add the missing frontmatter fields before relying on this source for cross-device memory review."
+    });
+  }
+  const byTopic = groupSourcesByTopic(input.indexState.sources);
+  for (const [topic, sources] of byTopic.entries()) {
+    if (sources.length === 1) {
+      findings.push({
+        id: `sparse_topic:${topic}`,
+        severity: "info",
+        kind: "sparse_topic",
+        topic,
+        ...sources[0]?.path ? { path: sources[0].path } : {},
+        message: `topic ${topic} has only one active memory source`,
+        suggested_action: "Decide whether the topic needs more coverage or should stay intentionally narrow."
+      });
+    }
+    const hasProjectSource = sources.some((source) => isProjectMemorySource(source, input.project));
+    const hasNonProjectScope = sources.some((source) => source.memory_scope === "global" || source.memory_scope === "cross-agent");
+    if (hasProjectSource && hasNonProjectScope) {
+      findings.push({
+        id: `scope_gap:${topic}`,
+        severity: "info",
+        kind: "scope_gap",
+        topic,
+        message: `topic ${topic} mixes project and non-project memory scopes`,
+        suggested_action: `Use skillwiki memory recall --project ${input.project} --topic ${topic} --scope <project|global|cross-agent|all> when reviewing this topic.`
+      });
+    }
+    if (sources.length >= 3) {
+      findings.push({
+        id: `consolidation_candidate:${topic}`,
+        severity: "info",
+        kind: "consolidation_candidate",
+        topic,
+        message: `topic ${topic} has ${sources.length} active memory sources and may be ready for consolidation`,
+        suggested_action: "Review this topic in office-hours or proj-distill before promoting or merging related memory pages."
+      });
+    }
+  }
+  return findings.sort(compareMemoryReviewFindings);
+}
+function parseInvalidTopicWarning(warning) {
+  const match = warning.match(/^(.*): invalid memory topic slug (.+)$/);
+  if (!match) return null;
+  return {
+    path: match[1] ?? "",
+    topic: match[2] ?? ""
+  };
+}
+function groupSourcesByTopic(sources) {
+  const byTopic = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    for (const topic of source.topics) {
+      const list = byTopic.get(topic) ?? [];
+      list.push(source);
+      byTopic.set(topic, list);
+    }
+  }
+  return byTopic;
+}
+function compareMemoryReviewFindings(a, b) {
+  return severityRank(b.severity) - severityRank(a.severity) || a.kind.localeCompare(b.kind) || (a.topic ?? "").localeCompare(b.topic ?? "") || (a.path ?? "").localeCompare(b.path ?? "") || a.id.localeCompare(b.id);
+}
+function severityRank(severity) {
+  return severity === "warn" ? 2 : 1;
+}
 function renderMemoryIndexStatusHint(status) {
   if (!status.cache_present) {
     return `memory index cache missing for ${status.project}; rebuild with memory index --project ${status.project}`;
@@ -9535,6 +9744,9 @@ function normalizeRecallScope(value) {
   if (!value) return void 0;
   return isRecallScope(value) ? value : void 0;
 }
+function isValidMemoryTopicSlug(value) {
+  return /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
 function isRecallScope(value) {
   return value === "project" || value === "global" || value === "cross-agent" || value === "all";
 }
@@ -9562,6 +9774,12 @@ function renderRecallHint(topic, sources) {
   if (sources.length === 0) return `no memory sources found for topic ${topic}`;
   return sources.map((source) => `${source.updated} ${source.title} (${source.path}) \u2014 ${source.summary}`).join("\n");
 }
+function renderMemoryReviewHint(project, status, findings) {
+  const warns = findings.filter((finding) => finding.severity === "warn").length;
+  const infos = findings.length - warns;
+  const cacheStatus = !status.cache_present ? "cache missing" : status.stale ? "cache stale" : "cache current";
+  return `memory review for ${project}: ${findings.length} finding(s) (${warns} warn, ${infos} info); ${cacheStatus}`;
+}
 function memoryCacheRelPath(project) {
   return `.skillwiki/memory/${project}/topics.json`;
 }
@@ -9582,46 +9800,11 @@ function dedupePages(pages) {
   }
   return out;
 }
-async function readMemorySource(page, project, warnings) {
-  const text = await readPage(page);
-  const fm = extractFrontmatter(text);
-  if (!fm.ok) return null;
-  const topics = normalizeMemoryTopics(fm.data.memory_topics, page.relPath, warnings);
-  if (topics.length === 0) return null;
-  const projects = memoryProjects(page.relPath, fm.data);
-  const scope = stringField2(fm.data.memory_scope);
-  if (!projects.includes(project) && scope !== "global" && scope !== "cross-agent") return null;
-  const privacy = stringField2(fm.data.memory_privacy) || "local";
-  if (privacy === "secret-blocked") {
-    warnings.push(`${page.relPath}: skipped secret-blocked memory`);
-    return null;
-  }
-  const status = stringField2(fm.data.memory_status) || "active";
-  if (status === "archived" || status === "rejected") return null;
-  const split = splitFrontmatter(text);
-  const body = split.ok ? split.data.body : text;
-  const updated = stringField2(fm.data.last_seen) || stringField2(fm.data.updated) || stringField2(fm.data.ingested) || dateFromPath2(page.relPath);
-  const title = stringField2(fm.data.title) || page.relPath.split("/").pop()?.replace(/\.md$/, "") || page.relPath;
-  return {
-    path: page.relPath,
-    title,
-    summary: summarize2(body),
-    updated,
-    hash: createHash8("sha256").update(Buffer.from(body, "utf8")).digest("hex"),
-    topics,
-    project,
-    ...stringField2(fm.data.memory_kind) ? { memory_kind: stringField2(fm.data.memory_kind) } : {},
-    ...scope ? { memory_scope: scope } : {},
-    ...stringField2(fm.data.memory_policy) ? { memory_policy: stringField2(fm.data.memory_policy) } : {},
-    memory_privacy: privacy,
-    memory_status: status
-  };
-}
 function normalizeMemoryTopics(value, path, warnings) {
   const rawTopics = typeof value === "string" ? [value] : stringArray(value);
   const topics = [];
   for (const topic of rawTopics) {
-    if (!/^[a-z0-9][a-z0-9-]*$/.test(topic)) {
+    if (!isValidMemoryTopicSlug(topic)) {
       warnings.push(`${path}: invalid memory topic slug ${topic}`);
       continue;
     }
@@ -11836,6 +12019,15 @@ memoryCmd.command("recall [vault]").description("recall bounded source summaries
     limit: opts.limit
   }), v.vault, { postCommit: false });
 });
+memoryCmd.command("review [vault]").description("review deterministic memory gaps and cache drift without writing").requiredOption("--project <slug>", "project slug").option("--dry-run", "preview only; writes are not supported on this surface", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runMemoryReview({
+    vault: v.vault,
+    project: opts.project,
+    dryRun: !!opts.dryRun
+  }), v.vault, { postCommit: false });
+});
 memoryCmd.command("import [vault]").description("preview or apply local memory imports into raw captures").requiredOption("--from <path>", "source file or directory to scan").requiredOption("--project <slug>", "project slug").option("--dry-run", "preview only; do not write captures", false).option("--apply", "write validated raw captures for ready entries", false).option("--max-bytes <n>", "reject source files above this size", (s) => parseInt(s, 10), 2e5).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "private": true,
   "files": [
     "wiki-*",