skillwiki 0.5.0 → 0.5.3

package/dist/cli.js

@@ -59,7 +59,8 @@ var ExitCode = {
   SYNC_PUSH_FAILED: 42,
   SYNC_PULL_FAILED: 43,
   BACKUP_SYNC_FAILED: 44,
-  BACKUP_RESTORE_CONFLICTS: 45
+  BACKUP_RESTORE_CONFLICTS: 45,
+  USAGE: 46
 };
 
 // ../shared/src/json-output.ts
@@ -91,7 +92,8 @@ var TypedKnowledgeSchema = z.object({
   contradictions: z.array(z.string()).optional(),
   provenance: z.enum(["research", "project", "mixed"]).optional(),
   provenance_projects: z.array(wikilink).optional(),
-  work_items: z.array(wikilink).optional()
+  work_items: z.array(wikilink).optional(),
+  stale_ttl: z.number().int().positive().optional()
 }).superRefine((v, ctx) => {
   if (v.provenance && v.provenance !== "research" && (!v.provenance_projects || v.provenance_projects.length === 0)) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "required when provenance != research" });
@@ -1004,8 +1006,10 @@ function isLegacyCitationStyle(body) {
   return false;
 }
 function hasOrphanedCitations(body) {
-  const stripped = stripFences(body.replace(FRONTMATTER, ""));
+  const noFm = body.replace(FRONTMATTER, "");
+  const stripped = stripFences(noFm);
   const lines = stripped.split("\n");
+  const rawLines = noFm.split("\n");
   let inSources = false;
   let sourcesEnded = false;
   let sourcesStartLine = -1;
@@ -1025,10 +1029,13 @@ function hasOrphanedCitations(body) {
       }
       continue;
     }
-    const isListItem = /^\s*[-*]\s+/.test(line);
+    const isListItem = /^\s*(?:[-*]|\d+\.)\s+/.test(line);
     const hasMarker = /\^\[raw\//.test(line);
+    const hasBacktickRawPath = /`raw\/[^`]+`/.test(rawLines[i]);
     if (isListItem && hasMarker) {
       lastNonBlankInSources = i;
+    } else if (isListItem && hasBacktickRawPath) {
+      lastNonBlankInSources = i;
     } else if (hasMarker && !isListItem) {
       return true;
     } else {
@@ -1835,6 +1842,42 @@ async function runIndexCheck(input) {
 // src/commands/stale.ts
 import { readdir as readdir4, rename as rename2, mkdir as mkdir6, readFile as readFile10 } from "fs/promises";
 import { join as join13 } from "path";
+
+// src/parsers/expiry-annotations.ts
+var HEADING_RE = /^#{1,6}\s+(.+)$/;
+var ANNOTATION_RE = /^<!--\s*expires:\s*(\d{4}-\d{2}-\d{2})(?:\s+refresh:\s*(weekly|monthly|quarterly))?(?:\s+source:\s*(\S+))?\s*-->$/;
+var VALID_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isValidDate(s) {
+  if (!VALID_DATE_RE.test(s)) return false;
+  const d = /* @__PURE__ */ new Date(s + "T00:00:00Z");
+  return !Number.isNaN(d.getTime()) && s === d.toISOString().slice(0, 10);
+}
+function parseExpiryAnnotations(content, pagePath) {
+  const lines = content.split("\n");
+  const annotations = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(ANNOTATION_RE);
+    if (!match) continue;
+    const expires = match[1];
+    if (!isValidDate(expires)) continue;
+    if (i === 0) continue;
+    const prevLine = lines[i - 1];
+    const headingMatch = prevLine.match(HEADING_RE);
+    if (!headingMatch) continue;
+    annotations.push({
+      page: pagePath,
+      heading: headingMatch[1].trim(),
+      line: i + 1,
+      // 1-indexed
+      expires,
+      refresh: match[2],
+      source: match[3]
+    });
+  }
+  return annotations;
+}
+
+// src/commands/stale.ts
 function daysSince(isoDate2) {
   return Math.floor((Date.now() - Date.parse(isoDate2)) / 864e5);
 }
@@ -1852,6 +1895,12 @@ async function runStale(input) {
     projectSlugs = (await readdir4(projectsDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
   } catch {
   }
+  if (input.project) {
+    if (!projectSlugs.includes(input.project)) {
+      return { exitCode: ExitCode.USAGE, result: { ok: false, error: "UNKNOWN_PROJECT", detail: `Project "${input.project}" not found. Available: ${projectSlugs.join(", ") || "(none)"}` } };
+    }
+    projectSlugs = [input.project];
+  }
   for (const slug of projectSlugs) {
     const workPath = join13(projectsDir, slug, "work");
     let entries;
@@ -1893,9 +1942,10 @@ async function runStale(input) {
   function extractSlug(projectField) {
     return projectField.replace(/^\[\[/, "").replace(/\]\]$/, "").replace(/^"|"$/g, "");
   }
+  const TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "abandoned", "done", "invalid"]);
   const KIND_FROM_FILENAME = /^(?:\d{4}-\d{2}-\d{2})-(task|bug|idea|note|observation)-.+\.md$/;
   const LOOP_CYCLE_PATTERN = /loop-cycle-/;
-  const transcripts = scan.data.raw.filter((p) => p.relPath.startsWith("raw/transcripts/") && p.relPath.endsWith(".md"));
+  let transcripts = scan.data.raw.filter((p) => p.relPath.startsWith("raw/transcripts/") && p.relPath.endsWith(".md"));
   const claimedPaths = /* @__PURE__ */ new Set();
   const transcriptMeta = /* @__PURE__ */ new Map();
   for (const t of transcripts) {
@@ -1904,6 +1954,7 @@ async function runStale(input) {
       const fm = extractFrontmatter(content);
       let kind = fm.ok && typeof fm.data.kind === "string" ? fm.data.kind : "";
       let project = fm.ok && typeof fm.data.project === "string" ? fm.data.project : "";
+      if (input.project && !project.includes(input.project)) continue;
       let inferred = false;
       if (input.forceScan && !kind) {
         const basename = t.relPath.split("/").pop();
@@ -1948,7 +1999,7 @@ async function runStale(input) {
         const overlap = wWords.filter((w) => tWords.has(w)).length;
         if (dirName.includes(tSlug) || tSlug.includes(wSlug) || overlap >= 1) {
           claimedPaths.add(t.relPath);
-          if (status === "done" || status === "invalid") {
+          if (TERMINAL_STATUSES.has(status)) {
             staleTranscripts.push({ path: t.relPath, reason: `work item projects/${slug}/work/${dirName} is ${status}` });
           }
           break;
@@ -1958,7 +2009,7 @@ async function runStale(input) {
       for (const [dir, status] of workDirs) {
         if (dir.split("/").pop().startsWith(datePrefix)) {
           claimedPaths.add(t.relPath);
-          if (status === "done" || status === "invalid") {
+          if (TERMINAL_STATUSES.has(status)) {
             staleTranscripts.push({ path: t.relPath, reason: `work item ${dir} is ${status}` });
           }
           break;
@@ -2003,10 +2054,8 @@ async function runStale(input) {
       continue;
     }
     const hasSpec = files.includes("spec.md"), hasPlan = files.includes("plan.md"), hasWI = files.includes("work-item.md");
-    if (status === "done") {
-      doneWorkItems.push({ path: relDir, reason: "completed \u2014 should be archived" });
-    } else if (status === "invalid") {
-      doneWorkItems.push({ path: relDir, reason: "invalid \u2014 should be archived" });
+    if (TERMINAL_STATUSES.has(status)) {
+      doneWorkItems.push({ path: relDir, reason: `${status || "completed"} \u2014 should be archived` });
     } else if (hasSpec && !hasPlan) {
       incompleteWorkItems.push({ path: relDir, reason: "has spec but no plan" });
     } else if (hasWI && !hasSpec && !hasPlan) {
@@ -2019,16 +2068,53 @@ async function runStale(input) {
       const text = await readFile10(join13(input.vault, page.relPath), "utf8");
       const fm = extractFrontmatter(text);
       if (fm.ok && typeof fm.data.updated === "string") {
+        if (input.project) {
+          const pp = fm.data.provenance_projects;
+          const linked = Array.isArray(pp) && pp.some((p) => String(p).includes(input.project));
+          if (!linked) continue;
+        }
         const age = daysSince(fm.data.updated);
-        if (age >= input.days) {
-          stale.push({ page: page.relPath, reason: `updated ${age} days ago (threshold: ${input.days})` });
+        const threshold = typeof fm.data.stale_ttl === "number" && fm.data.stale_ttl > 0 ? fm.data.stale_ttl : input.days;
+        if (age >= threshold) {
+          stale.push({ page: page.relPath, reason: `updated ${age} days ago (threshold: ${threshold})` });
         }
       }
     } catch {
     }
   }
+  const staleSections = [];
+  for (const page of scan.data.typedKnowledge) {
+    try {
+      const text = await readFile10(join13(input.vault, page.relPath), "utf8");
+      const projectFilter = input.project;
+      if (projectFilter) {
+        const fm = extractFrontmatter(text);
+        if (fm.ok) {
+          const pp = fm.data.provenance_projects;
+          const linked = Array.isArray(pp) && pp.some((p) => String(p).includes(projectFilter));
+          if (!linked) continue;
+        }
+      }
+      const annotations = parseExpiryAnnotations(text, page.relPath);
+      for (const ann of annotations) {
+        if (daysSince(ann.expires) >= 0) {
+          staleSections.push({
+            page: ann.page,
+            heading: ann.heading,
+            line: ann.line,
+            expires: ann.expires,
+            refresh: ann.refresh,
+            source: ann.source,
+            reason: `section "${ann.heading}" expired on ${ann.expires}`
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   if (input.archive) {
-    const archiveDir = join13(input.vault, "_archive", (/* @__PURE__ */ new Date()).toISOString().slice(0, 10));
+    const archiveDir = join13(input.vault, "_archive", today);
     await mkdir6(archiveDir, { recursive: true });
     const citedRawPaths = /* @__PURE__ */ new Set();
     for (const page of scan.data.typedKnowledge) {
@@ -2082,7 +2168,7 @@ async function runStale(input) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
-  const total = stale.length + staleTranscripts.length + unclaimedTranscripts.length + incompleteWorkItems.length + doneWorkItems.length;
+  const total = stale.length + staleTranscripts.length + unclaimedTranscripts.length + incompleteWorkItems.length + doneWorkItems.length + staleSections.length;
   const hintLines = [];
   if (stale.length > 0) hintLines.push(`stale_pages: ${stale.length}`, ...stale.map((p) => `  ${p.page}: ${p.reason}`));
   if (staleTranscripts.length > 0) hintLines.push(`stale_transcripts: ${staleTranscripts.length}`, ...staleTranscripts.map((t) => `  ${t.path}: ${t.reason}`));
@@ -2090,6 +2176,7 @@ async function runStale(input) {
     hint: ${t.hint}` : ""}`));
   if (incompleteWorkItems.length > 0) hintLines.push(`incomplete_work_items: ${incompleteWorkItems.length}`, ...incompleteWorkItems.map((w) => `  ${w.path}: ${w.reason}`));
   if (doneWorkItems.length > 0) hintLines.push(`done_work_items: ${doneWorkItems.length}`, ...doneWorkItems.map((w) => `  ${w.path}: ${w.reason}`));
+  if (staleSections.length > 0) hintLines.push(`stale_sections: ${staleSections.length}`, ...staleSections.map((s) => `  ${s.page}#${s.heading}: ${s.reason}`));
   if (archived.length > 0) hintLines.push(`archived: ${archived.length}`, ...archived.map((a) => `  ${a}`));
   if (hintLines.length === 0) hintLines.push("no stale transcripts or incomplete work items");
   return { exitCode: total > 0 ? ExitCode.STALE_PAGE : ExitCode.OK, result: ok({
@@ -2098,6 +2185,7 @@ async function runStale(input) {
     unclaimed_transcripts: unclaimedTranscripts,
     incomplete_work_items: incompleteWorkItems,
     done_work_items: doneWorkItems,
+    stale_sections: staleSections,
     archived,
     humanHint: hintLines.join("\n")
   }) };
@@ -2466,11 +2554,11 @@ function buildCliSurface() {
   program2.command("index-check").option("--wiki <name>");
   program2.command("index-link-format").option("--wiki <name>");
   program2.command("topic-map-check").option("--threshold <n>").option("--wiki <name>");
-  program2.command("stale").option("--archive").option("--days <n>").option("--force-scan").option("--wiki <name>");
+  program2.command("stale").option("--archive").option("--days <n>").option("--force-scan").option("--project <slug>").option("--refresh").option("--wiki <name>");
   program2.command("claim").option("--project <slug>").option("--slug <slug>").option("--wiki <name>");
   program2.command("pagesize").option("--lines <n>").option("--wiki <name>");
   program2.command("log-rotate").option("--threshold <n>").option("--apply").option("--wiki <name>");
-  program2.command("lint").option("--days <n>").option("--lines <n>").option("--log-threshold <n>").option("--fix").option("--wiki <name>");
+  program2.command("lint").option("--days <n>").option("--lines <n>").option("--log-threshold <n>").option("--fix").option("--only <bucket>").option("--wiki <name>");
   program2.command("config");
   program2.command("doctor");
   program2.command("status").option("--wiki <name>");
@@ -2615,8 +2703,8 @@ function extractSourceEntries(rawFm) {
   return entries;
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "missing_diagram", "cli_refs"];
+var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview", "missing_diagram"];
+var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
 async function runLint(input) {
   const buckets = {};
   const fixed = [];
@@ -2741,7 +2829,7 @@ async function runLint(input) {
       const hasOverview = /^## Overview/m.test(body);
       if (!hasOverview) noOverview.push(page.relPath);
       const bodyFirst15 = body.split("\n").slice(0, 15).join("\n");
-      if (!/^##\s+TL;\s*DR/m.test(bodyFirst15)) missingTldrFlags.push(page.relPath);
+      if (!/^>\s*\*\*TL;DR:?\*\*/m.test(bodyFirst15) && !/^##\s+TL;\s*DR/m.test(bodyFirst15)) missingTldrFlags.push(page.relPath);
       const fmData = extractFrontmatter(text);
       const pageTags = fmData.ok && Array.isArray(fmData.data.tags) ? fmData.data.tags : [];
       if (pageTags.includes("architecture") && !body.includes("```mermaid")) {
@@ -2785,7 +2873,7 @@ async function runLint(input) {
         const text = await readPage(specPage);
         const fm = extractFrontmatter(text);
         if (fm.ok) {
-          specStatus = fm.data.status;
+          specStatus = typeof fm.data.status === "string" ? fm.data.status : void 0;
           specStarted = fm.data.started;
         }
       }
@@ -2840,6 +2928,27 @@ async function runLint(input) {
       }
     }
     if (cliRefFlags.length > 0) buckets.cli_refs = cliRefFlags;
+    const staleSectionFlags = [];
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const approachingThreshold = 7;
+    for (const page of scan.data.typedKnowledge) {
+      try {
+        const text = await readPage(page);
+        const annotations = parseExpiryAnnotations(text, page.relPath);
+        for (const ann of annotations) {
+          if (ann.expires < today) {
+            staleSectionFlags.push(`${page.relPath}: section "${ann.heading}" expired on ${ann.expires}`);
+          } else {
+            const daysUntilExpiry = Math.floor((Date.parse(ann.expires) - Date.now()) / 864e5);
+            if (daysUntilExpiry <= approachingThreshold) {
+              staleSectionFlags.push(`${page.relPath}: section "${ann.heading}" expires in ${daysUntilExpiry} day(s) (${ann.expires})`);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    if (staleSectionFlags.length > 0) buckets.stale_sections = staleSectionFlags;
     if (input.fix && legacyPages.length > 0) {
       const FENCE_RE2 = /```[\s\S]*?```/g;
       const INLINE_MARKER = /\^\[raw\/[^\]]+\]/g;
@@ -2986,16 +3095,26 @@ ${trimmedBody}`;
           }
           const body = split.data.body;
           const rawFm = split.data.rawFrontmatter;
-          const trimmedBody = body.replace(/^\n+/, "");
+          const lines = body.split("\n");
+          let insertIndex = 0;
+          for (let i = 0; i < lines.length; i++) {
+            if (/^# /.test(lines[i])) {
+              insertIndex = i + 1;
+              while (insertIndex < lines.length && lines[insertIndex].trim() === "") {
+                insertIndex++;
+              }
+              break;
+            }
+          }
+          if (insertIndex === 0) {
+            lines.splice(0, 0, "", "> **TL;DR:** ");
+          } else {
+            lines.splice(insertIndex, 0, "> **TL;DR:** ");
+          }
+          const trimmedFm = rawFm.endsWith("\n") ? rawFm : rawFm + "\n";
           const newContent = `---
-${rawFm}
----
-
-## TL;DR
-
-- Pending summary.
-
-${trimmedBody}`;
+${trimmedFm}---
+${lines.join("\n")}`;
           await writeFile8(absPath, newContent, "utf8");
           fixed.push(relPath);
         } catch {
@@ -3096,6 +3215,38 @@ ${newBody}`;
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const infoOut = INFO_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
+  if (input.only) {
+    const allKnown = [...ERROR_ORDER, ...WARNING_ORDER, ...INFO_ORDER];
+    if (!allKnown.includes(input.only)) {
+      return {
+        exitCode: ExitCode.USAGE,
+        result: { ok: false, error: "UNKNOWN_BUCKET", detail: `Unknown bucket "${input.only}". Valid: ${allKnown.join(", ")}` }
+      };
+    }
+    const match = [...errorOut, ...warningOut, ...infoOut].filter((b) => b.kind === input.only);
+    const severity = ERROR_ORDER.includes(input.only) ? "error" : WARNING_ORDER.includes(input.only) ? "warning" : "info";
+    const filtered = severity === "error" ? { error: match, warning: [], info: [] } : severity === "warning" ? { error: [], warning: match, info: [] } : { error: [], warning: [], info: match };
+    const fSummary = {
+      errors: filtered.error.reduce((n, b) => n + b.items.length, 0),
+      warnings: filtered.warning.reduce((n, b) => n + b.items.length, 0),
+      info: filtered.info.reduce((n, b) => n + b.items.length, 0)
+    };
+    let fExit = ExitCode.OK;
+    if (fSummary.errors > 0) fExit = ExitCode.LINT_HAS_ERRORS;
+    else if (fSummary.warnings > 0 || fSummary.info > 0) fExit = ExitCode.LINT_HAS_WARNINGS;
+    return {
+      exitCode: fExit,
+      result: ok({
+        vault: { path: input.vault, source: input.source ?? "resolved" },
+        summary: fSummary,
+        by_severity: filtered,
+        fixed,
+        unresolved,
+        humanHint: `--only ${input.only}
+${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items.length}`).join("\n")}`
+      })
+    };
+  }
   const summary = {
     errors: errorOut.reduce((n, b) => n + b.items.length, 0),
     warnings: warningOut.reduce((n, b) => n + b.items.length, 0),
@@ -3203,7 +3354,7 @@ import { platform } from "os";
 
 // src/utils/auto-update.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync5, mkdirSync as mkdirSync2 } from "fs";
-import { join as join20, dirname as dirname8 } from "path";
+import { join as join20, dirname as dirname7 } from "path";
 import { spawn } from "child_process";
 
 // src/utils/update-consts.ts
@@ -3233,7 +3384,7 @@ function readCache(home) {
 }
 function writeCache(home, cache) {
   const p = cachePath(home);
-  mkdirSync2(dirname8(p), { recursive: true });
+  mkdirSync2(dirname7(p), { recursive: true });
   writeFileSync3(p, JSON.stringify(cache, null, 2));
 }
 function latestFromCache(home, currentVersion) {
@@ -3782,7 +3933,7 @@ async function runDoctor(input) {
 
 // src/commands/archive.ts
 import { rename as rename4, mkdir as mkdir8, readFile as readFile16, writeFile as writeFile9 } from "fs/promises";
-import { join as join23, dirname as dirname9 } from "path";
+import { join as join23, dirname as dirname8 } from "path";
 async function runArchive(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -3799,7 +3950,7 @@ async function runArchive(input) {
   if (!relPath) return { exitCode: ExitCode.ARCHIVE_TARGET_NOT_FOUND, result: err("ARCHIVE_TARGET_NOT_FOUND", { page: input.page }) };
   if (relPath.startsWith("_archive/")) return { exitCode: ExitCode.ARCHIVE_ALREADY_ARCHIVED, result: err("ARCHIVE_ALREADY_ARCHIVED", { page: relPath }) };
   const archivePath = join23("_archive", relPath).replace(/\\/g, "/");
-  await mkdir8(dirname9(join23(input.vault, archivePath)), { recursive: true });
+  await mkdir8(dirname8(join23(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
     const indexPath = join23(input.vault, "index.md");
@@ -4461,7 +4612,7 @@ async function runTranscripts(input) {
 
 // src/commands/project-index.ts
 import { readdir as readdir6, readFile as readFile18, writeFile as writeFile13, mkdir as mkdir9 } from "fs/promises";
-import { join as join27, dirname as dirname10 } from "path";
+import { join as join27, dirname as dirname9 } from "path";
 var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function runProjectIndex(input) {
   const slug = input.slug;
@@ -4575,7 +4726,7 @@ Autogenerated by \`skillwiki project-index\` on ${today}.
   }
   if (input.apply) {
     try {
-      await mkdir9(dirname10(indexPath), { recursive: true });
+      await mkdir9(dirname9(indexPath), { recursive: true });
       await writeFile13(indexPath, body, "utf8");
     } catch (e) {
       return {
@@ -5630,7 +5781,7 @@ async function runSyncPull(input) {
 
 // src/commands/backup.ts
 import { statSync as statSync4, readdirSync as readdirSync2, readFileSync as readFileSync9, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join32, relative as relative3, dirname as dirname11 } from "path";
+import { join as join32, relative as relative3, dirname as dirname10 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -5766,7 +5917,7 @@ async function runBackupRestore(input) {
         const resp = await client.send(new GetObjectCommand({ Bucket: input.bucket, Key: obj.Key }));
         const body = await resp.Body?.transformToByteArray();
         if (body) {
-          mkdirSync3(dirname11(localPath), { recursive: true });
+          mkdirSync3(dirname10(localPath), { recursive: true });
           writeFileSync4(localPath, Buffer.from(body));
           downloaded++;
         }
@@ -6451,10 +6602,10 @@ program.command("topic-map-check [vault]").description("check whether a topic ma
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runTopicMapCheck({ vault: v.vault, threshold: opts.threshold }), v.vault);
 });
-program.command("stale [vault]").description("identify stale transcripts and incomplete work items").option("--archive", "move stale items to _archive/", false).option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 3).option("--force-scan", "infer kind/project from filename and content when frontmatter is missing", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("stale [vault]").description("identify stale transcripts and incomplete work items").option("--archive", "move stale items to _archive/", false).option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 3).option("--force-scan", "infer kind/project from filename and content when frontmatter is missing", false).option("--project <slug>", "scope to a single project").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 runStale({ vault: v.vault, days: opts.days, archive: !!opts.archive, forceScan: !!opts.forceScan }), v.vault);
+  else emit(await runStale({ vault: v.vault, days: opts.days, archive: !!opts.archive, forceScan: !!opts.forceScan, project: opts.project }), v.vault);
 });
 program.command("claim <transcript> [vault]").description("claim an unclaimed transcript by creating a work item with source: link").option("--project <slug>", "project slug (overrides transcript frontmatter)").option("--slug <slug>", "work-item slug (defaults to transcript filename without date/kind prefix)").option("--wiki <name>", "wiki profile name").action(async (transcript, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -6471,7 +6622,7 @@ program.command("log-rotate [vault]").description("rotate or trim the vault log
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: !!opts.apply }), v.vault);
 });
-program.command("lint [vault]").description("run all vault health checks").option("--days <n>", "stale threshold", (s) => parseInt(s, 10), 90).option("--lines <n>", "pagesize threshold", (s) => parseInt(s, 10), 200).option("--log-threshold <n>", "log rotation threshold", (s) => parseInt(s, 10), 500).option("--fix", "auto-fix legacy_citation_style violations").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("lint [vault]").description("run all vault health checks").option("--days <n>", "stale threshold", (s) => parseInt(s, 10), 90).option("--lines <n>", "pagesize threshold", (s) => parseInt(s, 10), 200).option("--log-threshold <n>", "log rotation threshold", (s) => parseInt(s, 10), 500).option("--fix", "auto-fix legacy_citation_style violations").option("--only <bucket>", "run only the specified lint bucket").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 runLint({
@@ -6480,7 +6631,8 @@ program.command("lint [vault]").description("run all vault health checks").optio
     days: opts.days,
     lines: opts.lines,
     logThreshold: opts.logThreshold,
-    fix: opts.fix ?? false
+    fix: opts.fix ?? false,
+    only: opts.only
   }), v.vault);
 });
 var configCmd = program.command("config").description("manage skillwiki configuration");
@@ -6587,7 +6739,10 @@ syncCmd.command("pull [vault]").description("pull remote vault changes and lint"
 var backupCmd = program.command("backup").description("manage S3-compatible remote backup");
 backupCmd.command("sync [vault]").description("sync vault to S3-compatible remote backup").option("--dry-run", "list actions without executing").option("--bucket <name>", "S3 bucket name").option("--endpoint <url>", "S3 endpoint URL").option("--region <region>", "S3 region", "us-east-1").option("--prune", "delete orphaned S3 objects not in vault", 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 });
+  if (!v.ok) {
+    emit({ exitCode: v.exitCode, result: v.payload });
+    return;
+  }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
   const dotenv = await parseDotenvFile(configPath(home));
   emit(await runBackupSync({
@@ -6603,7 +6758,10 @@ backupCmd.command("sync [vault]").description("sync vault to S3-compatible remot
 });
 backupCmd.command("restore [vault]").description("restore vault from S3-compatible remote backup").option("--bucket <name>", "S3 bucket name").option("--endpoint <url>", "S3 endpoint URL").option("--region <region>", "S3 region", "us-east-1").option("--target <dir>", "restore target directory (defaults to vault)").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 });
+  if (!v.ok) {
+    emit({ exitCode: v.exitCode, result: v.payload });
+    return;
+  }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
   const dotenv = await parseDotenvFile(configPath(home));
   emit(await runBackupRestore({

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "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.5.0",
+  "version": "0.5.3",
   "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,11 +1,10 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "private": true,
   "files": [
     "wiki-*",
     "proj-*",
-    "dev-loop-research",
     "using-skillwiki",
     ".claude-plugin",
     ".codex-plugin",

package/skills/using-skillwiki/SKILL.md

@@ -71,7 +71,7 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `wiki-canvas` | Generate Obsidian Canvas visualization from vault graph data |
 | `proj-decide` | Write an Architectural Decision Record (ADR) |
 | `wiki-gate-plan-mode` | Toggle EnterPlanMode gating — force superpowers planning instead of built-in plan mode |
-| `dev-loop-research` | Standalone research agent — scans repo + vault health, outputs prioritized work-item recommendations |
+| `dev-loop:research` | Research agent for dev-loop IDLE — scans repo + vault health, outputs prioritized work-item recommendations (formerly `/dev-loop-research`) |
 ## CLI Backbone
 All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
 Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.

package/skills/wiki-crystallize/SKILL.md

@@ -16,7 +16,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 1. Identify type: entity / concept / comparison / query / summary.
 2. Set `provenance:`. Default `research`. If in project context: `project` with `provenance_projects: ["[[slug]]"]`.
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
-- `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+- `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
 - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
 4. `skillwiki validate <page>`. If non-zero, STOP.
 5. Apply writes: page → `index.md` → `log.md`.

package/skills/wiki-ingest/SKILL.md

@@ -21,7 +21,7 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
 3. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
 4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers). Every page MUST include:
-- `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+- `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
 - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
 5. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
 6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.