skillwiki 0.9.21 → 0.9.23

package/dist/cli.js

@@ -8,10 +8,6 @@ import {
   normalizeDistTag,
   semverGt
 } from "./chunk-E6UWZ3S3.js";
-import {
-  git,
-  gitStrict
-} from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
 import { join as join49 } from "path";
@@ -3529,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");
@@ -9142,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 };
@@ -9201,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) {
@@ -9294,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}`;
@@ -9539,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";
 }
@@ -9566,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`;
 }
@@ -9586,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;
     }
@@ -10154,6 +10333,19 @@ ${body}`;
 import { existsSync as existsSync17 } from "fs";
 import { join as join42 } from "path";
 
+// src/utils/git.ts
+import { execFileSync } from "child_process";
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function gitStrict(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
 // src/utils/sync-lock.ts
 import { existsSync as existsSync16, mkdirSync as mkdirSync6, readFileSync as readFileSync11, renameSync as renameSync2, unlinkSync as unlinkSync5, writeFileSync as writeFileSync7 } from "fs";
 import { join as join41 } from "path";
@@ -10264,6 +10456,15 @@ var VAULT_GENERATED_COMMIT_EXCLUDES = [
   ...VAULT_GENERATED_COMMIT_PATHS.map((path) => `:!${path}`)
 ];
 var VAULT_COMMIT_PATHSPEC = [".", ...VAULT_GENERATED_COMMIT_EXCLUDES];
+function stageVaultContentChanges(vault) {
+  gitStrict(vault, ["add", "-A", "--", "."]);
+  for (const generatedPath of VAULT_GENERATED_COMMIT_PATHS) {
+    try {
+      gitStrict(vault, ["reset", "HEAD", "--", generatedPath]);
+    } catch (_e) {
+    }
+  }
+}
 
 // src/commands/sync.ts
 function runSyncStatus(input) {
@@ -10390,13 +10591,7 @@ async function runSyncPush(input) {
     };
   }
   try {
-    gitStrict(vault, ["add", "-A", "--", ...VAULT_COMMIT_PATHSPEC]);
-    for (const generatedPath of VAULT_GENERATED_COMMIT_PATHS) {
-      try {
-        gitStrict(vault, ["reset", "HEAD", "--", generatedPath]);
-      } catch (_e) {
-      }
-    }
+    stageVaultContentChanges(vault);
   } catch (e) {
     return {
       exitCode: ExitCode.SYNC_PUSH_FAILED,
@@ -11383,15 +11578,8 @@ async function postCommit(vault, exitCode) {
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain", "--", ...VAULT_COMMIT_PATHSPEC]);
   if (!porcelain || porcelain.trim().length === 0) return;
-  const { gitStrict: gitStrict2 } = await import("./git-M4WGJ5G3.js");
   try {
-    gitStrict2(vault, ["add", "-A", "--", "."]);
-    for (const generatedPath of VAULT_GENERATED_COMMIT_PATHS) {
-      try {
-        gitStrict2(vault, ["reset", "HEAD", "--", generatedPath]);
-      } catch (_e) {
-      }
-    }
+    stageVaultContentChanges(vault);
   } catch (e) {
     process.stderr.write(`auto-commit: git add failed: ${String(e)}
 `);
@@ -11399,7 +11587,7 @@ async function postCommit(vault, exitCode) {
   }
   const commitMessage = lastOps.map((op) => `${op.operation}: ${op.summary} (${op.files.length} files)`).join("; ");
   try {
-    gitStrict2(vault, ["commit", "-m", commitMessage]);
+    gitStrict(vault, ["commit", "-m", commitMessage]);
   } catch (e) {
     process.stderr.write(`auto-commit: git commit failed: ${String(e)}
 `);
@@ -11831,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.21",
+  "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.21",
+  "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.21",
+  "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.21",
+  "version": "0.9.23",
   "private": true,
   "files": [
     "wiki-*",

package/dist/chunk-TPS5XD2J.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-
-// src/utils/git.ts
-import { execFileSync } from "child_process";
-function git(cwd, args) {
-  try {
-    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-  } catch {
-    return "";
-  }
-}
-function gitStrict(cwd, args) {
-  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-}
-
-export {
-  git,
-  gitStrict
-};

package/dist/git-M4WGJ5G3.js

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-import {
-  git,
-  gitStrict
-} from "./chunk-TPS5XD2J.js";
-export {
-  git,
-  gitStrict
-};