skillwiki 0.9.29 → 0.9.31

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import {
   ExitCode,
+  FLEET_REL_PATH,
+  SATELLITE_STALE_MS,
   TypedKnowledgeSchema,
   appendLastOp,
   assessSourceIdentity,
@@ -8,12 +10,15 @@ import {
   configPath,
   detectSchema,
   err,
+  evaluateSatelliteRunHealth,
   extractCitationMarkers,
   extractFrontmatter,
   extractTaxonomy,
   findPlugin,
   fixPathTooLong,
   isBlockedHost,
+  isFailedRunStatus,
+  loadFleetManifest,
   ok,
   parseDotenvFile,
   parseDotenvText,
@@ -21,6 +26,8 @@ import {
   readCliPackageJson,
   readLastOp,
   readPage,
+  readSatelliteLatestRunFromText,
+  resolveFleetHostId,
   resolveInitTimePath,
   resolveRuntimePath,
   runAudit,
@@ -32,6 +39,7 @@ import {
   runDoctor,
   runFleetContext,
   runFleetValidate,
+  runFrontmatterFix,
   runGraphBuild,
   runIndexCheck,
   runIndexLinkFormat,
@@ -54,19 +62,20 @@ import {
   runTopicMapCheck,
   runValidate,
   safeWritePage,
+  satelliteLatestRunPath,
   scanSensitiveContent,
   scanVault,
   splitFrontmatter,
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-T7XG3WFK.js";
+} from "./chunk-6G7RAAOS.js";
 import {
   normalizeDistTag
 } from "./chunk-E6UWZ3S3.js";
 
 // src/cli.ts
-import { join as join24 } from "path";
+import { join as join25 } from "path";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -1760,82 +1769,6 @@ ${migratedBody}${newFooter}`;
   };
 }
 
-// src/commands/frontmatter-fix.ts
-function isoToday() {
-  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-}
-function fixFrontmatter(rawFm) {
-  const additions = [];
-  if (!/^created:/m.test(rawFm)) additions.push(`created: ${isoToday()}`);
-  if (!/^updated:/m.test(rawFm)) additions.push(`updated: ${isoToday()}`);
-  if (!/^tags:/m.test(rawFm)) additions.push("tags: []");
-  if (!/^sources:/m.test(rawFm)) additions.push("sources: []");
-  if (!/^provenance:/m.test(rawFm)) additions.push("provenance: research");
-  if (additions.length === 0) return rawFm;
-  return rawFm.trimEnd() + "\n" + additions.join("\n") + "\n";
-}
-function removeOrphanTagsLines(body) {
-  return body.split("\n").filter((line) => !/^tags:\s*\[/.test(line.trim())).join("\n");
-}
-async function runFrontmatterFix(input) {
-  const scan = await scanVault(input.vault);
-  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const fixed = [];
-  const skipped = [];
-  let unchanged = 0;
-  for (const page of scan.data.typedKnowledge) {
-    const text = await readPage(page);
-    const split = splitFrontmatter(text);
-    if (!split.ok) {
-      skipped.push(page.relPath);
-      continue;
-    }
-    const { rawFrontmatter, body } = split.data;
-    const newFm = fixFrontmatter(rawFrontmatter);
-    const newBody = removeOrphanTagsLines(body);
-    const newText = `---
-${newFm}
----
-${newBody}`;
-    if (newText === text) {
-      unchanged++;
-      continue;
-    }
-    if (!input.dryRun) {
-      const w = await safeWritePage(page.absPath, newText);
-      if (!w.ok) {
-        skipped.push(page.relPath);
-        continue;
-      }
-    }
-    fixed.push(page.relPath);
-  }
-  const exitCode = fixed.length > 0 ? ExitCode.MIGRATION_APPLIED : ExitCode.OK;
-  const hintLines = [`scanned: ${fixed.length + skipped.length + unchanged}`];
-  if (fixed.length > 0) hintLines.push(`fixed: ${fixed.length}`);
-  if (skipped.length > 0) hintLines.push(`skipped (parse error): ${skipped.length}`);
-  if (unchanged > 0) hintLines.push(`unchanged: ${unchanged}`);
-  if (input.dryRun && fixed.length > 0) hintLines.push("(dry run \u2014 no files written)");
-  if (!input.dryRun && fixed.length > 0) {
-    appendLastOp(input.vault, {
-      operation: "frontmatter-fix",
-      summary: `normalized frontmatter on ${fixed.length} page(s)`,
-      files: fixed,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    });
-  }
-  return {
-    exitCode,
-    result: ok({
-      scanned: fixed.length + skipped.length + unchanged,
-      fixed,
-      skipped,
-      unchanged,
-      humanHint: hintLines.join("\n")
-    })
-  };
-}
-
 // src/commands/update.ts
 import { execSync } from "child_process";
 import { join as join11 } from "path";
@@ -2418,7 +2351,10 @@ async function runSessionBrief(input) {
     const transcripts = await loadTranscriptInfo(scan.data.raw);
     const workItems = await loadWorkItems(scan.data.workItems);
     const digests = await loadTrendDigests(scan.data.typedKnowledge);
-    const healthWarnings = await loadHealthWarnings(input.vault);
+    const healthWarnings = [
+      ...await loadHealthWarnings(input.vault),
+      ...satelliteHealthWarnings(await loadSatelliteHealth(input.vault))
+    ];
     const memoryTopics = project ? await loadMemoryTopics(input.vault, project) : [];
     const latestLogs = newest(transcripts.filter((t) => t.kind === "session-log"), 3);
     const unclaimedCaptures = newest(transcripts.filter((t) => {
@@ -2628,6 +2564,31 @@ function appendTextSection(lines, title, items, empty) {
   }
   lines.push("");
 }
+async function loadSatelliteHealth(vaultPath) {
+  const health = evaluateSatelliteRunHealth(vaultPath, /* @__PURE__ */ new Date());
+  if (!health.failed && !health.stale) {
+    const runPath2 = satelliteLatestRunPath(vaultPath);
+    const hasRun = await readIfExists(runPath2);
+    if (!hasRun) return null;
+  }
+  if (health.failed) {
+    const fc = health.failureClass && health.failureClass.length > 0 ? health.failureClass : "unknown";
+    return `agent-memory-trends: last run failed (${fc})`;
+  }
+  if (health.stale && health.finishedAt) {
+    const finishedMs = Date.parse(health.finishedAt);
+    if (!Number.isNaN(finishedMs)) {
+      const ageHours = (Date.now() - finishedMs) / (60 * 60 * 1e3);
+      const hoursRounded = Math.floor(ageHours);
+      const datePart = health.finishedAt.slice(0, 10);
+      return `agent-memory-trends: no run in ${hoursRounded}h (last: ${datePart})`;
+    }
+  }
+  return null;
+}
+function satelliteHealthWarnings(warning) {
+  return warning ? [warning] : [];
+}
 async function loadHealthWarnings(vault) {
   const text = await readIfExists(join15(vault, ".skillwiki", "health.json"));
   if (!text) return [];
@@ -4356,16 +4317,333 @@ written: ${outPath}`
   };
 }
 
-// src/utils/auto-commit.ts
-import { existsSync as existsSync10 } from "fs";
+// src/commands/fleet-health.ts
+import { existsSync as existsSync10, readFileSync as readFileSync6 } from "fs";
+import { execSync as nodeExecSync } from "child_process";
+import { hostname as nodeHostname, platform as nodePlatform } from "os";
 import { join as join23 } from "path";
+var SSH_TIMEOUT_MS = 15e3;
+var TIMER_UNIT = "agent-memory-trends.timer";
+var SERVICE_UNIT = "agent-memory-trends.service";
+var SYSTEMD_SERVICE_FAILED_CLASS = "SYSTEMD_SERVICE_FAILED";
+function defaultDeps() {
+  return {
+    platform: () => nodePlatform(),
+    execSync: nodeExecSync
+  };
+}
+function formatAgeHours(finishedAt) {
+  if (!finishedAt) return "never";
+  const ts = Date.parse(finishedAt);
+  if (!Number.isFinite(ts)) return "unknown";
+  const hours = Math.floor((Date.now() - ts) / (60 * 60 * 1e3));
+  if (hours < 1) return "<1h";
+  return `${hours}h`;
+}
+function deriveRunFields(parsed) {
+  if (!parsed) {
+    return {
+      last_run_status: "unknown",
+      last_run_age: "never",
+      failure_class: "-",
+      runUnhealthy: false
+    };
+  }
+  const finishedAt = parsed.finished_at;
+  const age = formatAgeHours(finishedAt);
+  const fc = parsed.failure_class != null && String(parsed.failure_class).length > 0 ? String(parsed.failure_class) : "-";
+  if (isFailedRunStatus(parsed.status ?? "")) {
+    return {
+      last_run_status: "fail",
+      last_run_age: age,
+      failure_class: fc === "-" ? "fail" : fc,
+      runUnhealthy: true
+    };
+  }
+  if (finishedAt) {
+    const ts = Date.parse(finishedAt);
+    if (Number.isFinite(ts) && Date.now() - ts > SATELLITE_STALE_MS) {
+      return {
+        last_run_status: "success",
+        last_run_age: age,
+        failure_class: "-",
+        runUnhealthy: true
+      };
+    }
+  }
+  if (parsed.status === "success" || parsed.status === "ok") {
+    return {
+      last_run_status: "success",
+      last_run_age: age,
+      failure_class: "-",
+      runUnhealthy: false
+    };
+  }
+  return {
+    last_run_status: parsed.status ? "unknown" : "none",
+    last_run_age: age,
+    failure_class: "-",
+    runUnhealthy: false
+  };
+}
+function systemctlPropLocal(deps, unit, prop) {
+  if (deps.platform() !== "linux") return null;
+  try {
+    return deps.execSync(`systemctl ${prop} ${unit}`, {
+      encoding: "utf8",
+      timeout: 2e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function systemctlIsActiveLocal(deps, unit) {
+  const out = systemctlPropLocal(deps, unit, "is-active");
+  if (out === null) return "unknown";
+  return out === "active" ? "active" : "inactive";
+}
+function systemctlIsFailedLocal(deps, unit) {
+  return systemctlPropLocal(deps, unit, "is-failed") === "failed";
+}
+function applyServiceFailedOverlay(run, serviceFailed) {
+  if (!serviceFailed) return run;
+  return {
+    ...run,
+    last_run_status: "fail",
+    failure_class: run.failure_class === "-" ? SYSTEMD_SERVICE_FAILED_CLASS : run.failure_class,
+    runUnhealthy: true
+  };
+}
+function probeLocal(vaultPath, deps) {
+  const latestPath = satelliteLatestRunPath(vaultPath);
+  let parsed = null;
+  if (existsSync10(latestPath)) {
+    try {
+      const wire = readSatelliteLatestRunFromText(readFileSync6(latestPath, "utf8"));
+      if (wire) {
+        parsed = {
+          status: wire.status,
+          finished_at: wire.finishedAt,
+          failure_class: wire.failureClass ?? null
+        };
+      }
+    } catch {
+      parsed = null;
+    }
+  }
+  const timer = systemctlIsActiveLocal(deps, TIMER_UNIT);
+  const serviceFailed = systemctlIsFailedLocal(deps, SERVICE_UNIT);
+  const run = applyServiceFailedOverlay(deriveRunFields(parsed), serviceFailed);
+  const timerBad = deps.platform() === "linux" && timer === "inactive";
+  return {
+    timer,
+    last_run_status: run.last_run_status,
+    last_run_age: run.last_run_age,
+    failure_class: run.failure_class,
+    reachable: "yes",
+    runUnhealthy: run.runUnhealthy,
+    timerBad
+  };
+}
+function probeRemote(sshAlias, vaultPath, deps) {
+  const latest = satelliteLatestRunPath(vaultPath);
+  const remoteCmd = [
+    `cat ${shellQuote2(latest)} 2>/dev/null || true`,
+    "echo __SW_TIMER__",
+    `systemctl is-active ${TIMER_UNIT} 2>/dev/null || echo inactive`,
+    "echo __SW_FAILED__",
+    `systemctl is-failed ${SERVICE_UNIT} 2>/dev/null || echo unknown`
+  ].join("\n");
+  const sshCmd = `ssh -o ConnectTimeout=10 ${sshAlias} ${shellQuote2(remoteCmd)}`;
+  try {
+    const out = deps.execSync(sshCmd, {
+      encoding: "utf8",
+      timeout: SSH_TIMEOUT_MS,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const timerMarker = "__SW_TIMER__";
+    const failedMarker = "__SW_FAILED__";
+    const timerIdx = out.indexOf(timerMarker);
+    const jsonPart = timerIdx >= 0 ? out.slice(0, timerIdx) : out;
+    const afterTimer = timerIdx >= 0 ? out.slice(timerIdx + timerMarker.length) : "";
+    const failedIdx = afterTimer.indexOf(failedMarker);
+    const timerRaw = failedIdx >= 0 ? afterTimer.slice(0, failedIdx) : afterTimer;
+    const failedRaw = failedIdx >= 0 ? afterTimer.slice(failedIdx + failedMarker.length) : "";
+    const jsonText = jsonPart.trim();
+    const parsed = jsonText.startsWith("{") ? (() => {
+      const wire = readSatelliteLatestRunFromText(jsonText);
+      if (!wire) return null;
+      return {
+        status: wire.status,
+        finished_at: wire.finishedAt,
+        failure_class: wire.failureClass ?? null
+      };
+    })() : null;
+    const timerLine = timerRaw.trim().split("\n")[0]?.trim() ?? "unknown";
+    let timer = "unknown";
+    if (timerLine === "active") timer = "active";
+    else if (timerLine === "inactive") timer = "inactive";
+    const failedLine = failedRaw.trim().split("\n")[0]?.trim() ?? "unknown";
+    const serviceFailed = failedLine === "failed";
+    const run = applyServiceFailedOverlay(deriveRunFields(parsed), serviceFailed);
+    const timerBad = timer === "inactive";
+    return {
+      timer,
+      last_run_status: run.last_run_status,
+      last_run_age: run.last_run_age,
+      failure_class: run.failure_class,
+      reachable: "yes",
+      runUnhealthy: run.runUnhealthy,
+      timerBad
+    };
+  } catch {
+    return {
+      timer: "unknown",
+      last_run_status: "unknown",
+      last_run_age: "never",
+      failure_class: "-",
+      reachable: "no",
+      runUnhealthy: true,
+      timerBad: true
+    };
+  }
+}
+function shellQuote2(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function satelliteHosts(manifest) {
+  const out = [];
+  for (const [id, host] of Object.entries(manifest.hosts)) {
+    const sat = host.maintenance?.skillwiki_satellite;
+    if (sat?.enabled === true) {
+      out.push({ id, vaultPath: sat.vault_path, sshAlias: sat.ssh_alias, host });
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function hasDeclaredSshAccess(host, localHostId, satelliteAlias) {
+  const profile = host.access?.from?.[localHostId];
+  if (!profile) return false;
+  if (profile.status !== "configured" && profile.status !== "local") return false;
+  const aliases = profile.ssh_aliases ?? [];
+  return aliases.includes(satelliteAlias);
+}
+function formatTable(rows) {
+  if (rows.length === 0) return "no satellite hosts configured";
+  const header = "host | timer | last_run_status | last_run_age | failure_class | reachable";
+  const lines = rows.map(
+    (r) => `${r.host} | ${r.timer} | ${r.last_run_status} | ${r.last_run_age} | ${r.failure_class} | ${r.reachable}`
+  );
+  return [header, ...lines].join("\n");
+}
+function rowHealthy(reachable, timer, runUnhealthy, timerBad, platform2) {
+  if (reachable === "no-access") return true;
+  if (reachable === "no") return false;
+  if (runUnhealthy) return false;
+  if (platform2 === "linux" && timerBad) return false;
+  if (platform2 === "linux" && timer === "inactive") return false;
+  return true;
+}
+async function runFleetHealth(input) {
+  const deps = input.deps ?? defaultDeps();
+  const env = input.env ?? process.env;
+  const home = input.home ?? env.HOME ?? "";
+  const osHostname = input.osHostname ?? env.HOSTNAME ?? nodeHostname();
+  const vault = input.vault ?? env.WIKI_PATH;
+  const file = input.file ?? (vault ? join23(vault, FLEET_REL_PATH) : void 0);
+  if (!file) {
+    return {
+      exitCode: ExitCode.NO_VAULT_CONFIGURED,
+      result: err("NO_VAULT_CONFIGURED", { message: "vault path or --file required" })
+    };
+  }
+  const loaded = await loadFleetManifest(file);
+  if (!loaded.ok) {
+    if (loaded.error === "FILE_NOT_FOUND") {
+      return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: file }) };
+    }
+    return {
+      exitCode: ExitCode.FLEET_MANIFEST_INVALID,
+      result: err("INVALID_FLEET_MANIFEST", { path: file })
+    };
+  }
+  const resolved = await resolveFleetHostId({
+    manifest: loaded.manifest,
+    hostId: input.hostId,
+    env,
+    home,
+    osHostname
+  });
+  const localHostId = resolved.hostId;
+  const targets = satelliteHosts(loaded.manifest);
+  if (targets.length === 0) {
+    const humanHint2 = "no satellite hosts configured";
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({ hosts: [], humanHint: humanHint2 })
+    };
+  }
+  const rows = [];
+  for (const t of targets) {
+    const isLocal = localHostId === t.id;
+    if (isLocal) {
+      const p = probeLocal(t.vaultPath, deps);
+      const healthy = rowHealthy(p.reachable, p.timer, p.runUnhealthy, p.timerBad, deps.platform());
+      rows.push({
+        host: t.id,
+        timer: p.timer,
+        last_run_status: p.last_run_status,
+        last_run_age: p.last_run_age,
+        failure_class: p.failure_class,
+        reachable: p.reachable,
+        healthy
+      });
+    } else {
+      if (!hasDeclaredSshAccess(t.host, localHostId, t.sshAlias)) {
+        rows.push({
+          host: t.id,
+          timer: "unknown",
+          last_run_status: "unknown",
+          last_run_age: "never",
+          failure_class: "-",
+          reachable: "no-access",
+          healthy: true
+        });
+        continue;
+      }
+      const p = probeRemote(t.sshAlias, t.vaultPath, deps);
+      const healthy = rowHealthy(p.reachable, p.timer, p.runUnhealthy, p.timerBad, "linux");
+      rows.push({
+        host: t.id,
+        timer: p.timer,
+        last_run_status: p.last_run_status,
+        last_run_age: p.last_run_age,
+        failure_class: p.failure_class,
+        reachable: p.reachable,
+        healthy
+      });
+    }
+  }
+  const allHealthy = rows.every((r) => r.healthy);
+  const humanHint = formatTable(rows);
+  const exitCode = allHealthy ? ExitCode.OK : ExitCode.FLEET_SATELLITE_HEALTH_FAILED;
+  return {
+    exitCode,
+    result: ok({ hosts: rows, humanHint })
+  };
+}
+
+// src/utils/auto-commit.ts
+import { existsSync as existsSync11 } from "fs";
+import { join as join24 } from "path";
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
   const home = process.env.HOME ?? "";
   const dotenv = await parseDotenvFile(configPath(home));
   const autoCommit = process.env.AUTO_COMMIT ?? dotenv["AUTO_COMMIT"];
   if (autoCommit === "false") return;
-  if (!existsSync10(join23(vault, ".git"))) return;
+  if (!existsSync11(join24(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain", "--", ...VAULT_COMMIT_PATHSPEC]);
@@ -4411,7 +4689,7 @@ program.command("validate <file>").description("validate vault page frontmatter
   emit(await runValidate({ file, apply: !!opts.apply, vault }), vault);
 });
 program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path (default: <vault>/.skillwiki/graph.json)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
-  const out = opts.out ?? join24(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join25(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -4860,6 +5138,20 @@ fleetCmd.command("context [vault]").description("render compact Runtime Host Con
     user: process.env.USER
   }));
 });
+fleetCmd.command("health [vault]").description("read-only health probe for skillwiki satellite hosts").option("--file <path>", "fleet manifest path").option("--host-id <id>", "explicit current fleet host id").option("--json", "emit JSON result").action(async (vault, opts) => {
+  const r = await runFleetHealth({
+    vault,
+    file: opts.file,
+    hostId: opts.hostId,
+    json: !!opts.json,
+    env: process.env,
+    home: process.env.HOME ?? "",
+    cwd: process.cwd(),
+    osHostname: process.env.HOSTNAME,
+    user: process.env.USER
+  });
+  emit(r, vault);
+});
 program.command("mcp").description("start stdio Model Context Protocol server (read-only vault tools)").action(async () => {
   await runSkillwikiMcpStdio();
 });

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-T7XG3WFK.js";
+} from "./chunk-6G7RAAOS.js";
 import "./chunk-E6UWZ3S3.js";
 
 // src/mcp-entry.ts

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.29",
+  "version": "0.9.31",
   "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.29",
+  "version": "0.9.31",
   "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.29",
+  "version": "0.9.31",
   "private": true,
   "files": [
     "wiki-*",

package/skills/proj-distill/SKILL.md

@@ -32,6 +32,7 @@ When reading retros as source material:
    `provenance: project` and
    `provenance_projects: ["[[slug]]"]`. Validate with
    `skillwiki validate`.
+   - **Portable source references:** follow `using-skillwiki` → Portable Source References (commit-pinned GitHub URLs or repo-relative paths; not canonical `Source file:` / `Source inspected:` host paths).
    - **Tag hygiene:** `tags:` must only contain entries from
      `{vault}/SCHEMA.md` taxonomy. Never derive tags from prose text
      (lesson/evidence sections) — use only established taxonomy tags

package/skills/proj-work/SKILL.md

@@ -53,6 +53,7 @@ Rules:
 - Resolve `<vault-root>` via `skillwiki path` (never hardcode).
 - proj-work does NOT invoke any PRD skill — it provides paths only.
 - If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+- When `spec.md` or `plan.md` mentions repo files, follow `using-skillwiki` → Portable Source References.
 
 ## Pitfalls
 - **Wiki-as-truth fallacy**: tasks.md status markers are aspirational claims by previous sessions. They are often wrong. Always audit the actual file system before accepting a "DONE" label.

package/skills/skills/proj-distill/SKILL.md

@@ -32,6 +32,7 @@ When reading retros as source material:
    `provenance: project` and
    `provenance_projects: ["[[slug]]"]`. Validate with
    `skillwiki validate`.
+   - **Portable source references:** follow `using-skillwiki` → Portable Source References (commit-pinned GitHub URLs or repo-relative paths; not canonical `Source file:` / `Source inspected:` host paths).
    - **Tag hygiene:** `tags:` must only contain entries from
      `{vault}/SCHEMA.md` taxonomy. Never derive tags from prose text
      (lesson/evidence sections) — use only established taxonomy tags

package/skills/skills/proj-work/SKILL.md

@@ -53,6 +53,7 @@ Rules:
 - Resolve `<vault-root>` via `skillwiki path` (never hardcode).
 - proj-work does NOT invoke any PRD skill — it provides paths only.
 - If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+- When `spec.md` or `plan.md` mentions repo files, follow `using-skillwiki` → Portable Source References.
 
 ## Pitfalls
 - **Wiki-as-truth fallacy**: tasks.md status markers are aspirational claims by previous sessions. They are often wrong. Always audit the actual file system before accepting a "DONE" label.

package/skills/skills/using-skillwiki/SKILL.md

@@ -59,6 +59,15 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 ## Sensitive Content Policy
 Vault content must not contain live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets. This includes development-only and local-only credentials. Redact values before filing using `[REDACTED:<kind>]` or `[REDACTED:<kind>:<fingerprint>]`. If a source contains live secrets, stop and ask for a redacted source or explicit rotation/remediation direction; do not preserve the secret in `raw/`.
 
+## Portable Source References
+The vault is shared across hosts, so host-local absolute paths are not durable source identity.
+
+- Prefer commit-pinned GitHub URLs when the source file is in a pushed repository and the commit is known.
+- Otherwise prefer repo-relative identity in prose, such as repo slug + relative path.
+- Use vault-relative references or `[[wikilinks]]` for pages already inside the wiki.
+- Keep host-local absolute paths (`/Users/...`, `/home/...`, `file:///...`) only as clearly labeled observations such as `Observed on host: ...`, not as canonical `Source file:` or `Source inspected:` lines.
+- Do not use markdown links to local vault files when a `[[wikilink]]` should be used instead.
+
 ### Ad-hoc capture: three entry points
 | Entry | When | What happens |
 |-------|------|-------------|

package/skills/skills/wiki-crystallize/SKILL.md

@@ -17,6 +17,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
 - `> **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`).
+- When referring to local repo files in narrative prose, follow `using-skillwiki` → Portable Source References.
 For `comparison`, evaluation-style `query`, or research-summary pages, end the body with:
 ```markdown
 ## Decision Closeout
@@ -36,5 +37,6 @@ Use exactly one disposition. Keep this as a prompt/template convention; do not a
 ## Forbidden
 - Filing without explicit `provenance:`.
 - Updating `index.md` before `validate` passes.
+- Writing host-local absolute paths as canonical durable source references when a portable reference is available (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.