skillwiki 0.9.30 → 0.9.31

package/dist/{chunk-JENSKJP6.js → chunk-6G7RAAOS.js}

@@ -1170,8 +1170,9 @@ var FRONTMATTER = /^---\n[\s\S]*?\n---\n?/;
 function stripFences(body) {
   return body.replace(FENCE2, "").replace(INLINE_CODE, "");
 }
+var TILDE_FENCE = /~~~[\s\S]*?~~~/g;
 function stripFencedBlocks(body) {
-  return body.replace(FENCE2, "");
+  return body.replace(FENCE2, "").replace(TILDE_FENCE, "");
 }
 function extractCitationMarkers(body) {
   const stripped = stripFences(body);
@@ -2922,6 +2923,23 @@ function hasDuplicateFrontmatter(body) {
   }
   return false;
 }
+var CANONICAL_LOCAL_SOURCE_LABEL = /^\s*(?:>\s*)?(?:[-*+]\s*)?Source (?:file|inspected):/i;
+var LOCAL_ABSOLUTE_SOURCE_REF = /(?:file:\/\/(?:\/)?(?:Users|home)\/|\/(?:Users|home)\/)/;
+function hasCanonicalLocalSourceAssertion(body) {
+  const visibleBody = stripFencedBlocks(body);
+  return visibleBody.split(/\r?\n/).some(
+    (line) => CANONICAL_LOCAL_SOURCE_LABEL.test(line) && LOCAL_ABSOLUTE_SOURCE_REF.test(line)
+  );
+}
+function shouldCheckCanonicalLocalSourceAssertion(page) {
+  if (page.relPath.startsWith("raw/transcripts/")) return false;
+  if (/^projects\/[^/]+\/work\/[^/]+\/log\.md$/.test(page.relPath)) return false;
+  if (page.relPath.startsWith("raw/")) return true;
+  if (/^(entities|concepts|comparisons|queries|meta)\//.test(page.relPath)) return true;
+  if (/^projects\/[^/]+\/compound\//.test(page.relPath)) return true;
+  if (/^projects\/[^/]+\/work\/[^/]+\/(spec|plan)\.md$/.test(page.relPath)) return true;
+  return false;
+}
 function extractSourceEntries(rawFm) {
   const lines = rawFm.split(/\r?\n/);
   const sourcesLineIdx = lines.findIndex((l) => /^sources:/.test(l));
@@ -3196,14 +3214,18 @@ async function runLint(input) {
     if (subDirDupes.length > 0) {
       buckets.raw_subdirectory_duplicate = subDirDupes;
     }
-    const fileSourceUrlFlags = [];
+    const fileSourceUrlFlags = /* @__PURE__ */ new Set();
+    const fileSourceUrlFrontmatterFlags = /* @__PURE__ */ new Set();
     const rawIdentityConflicts = [];
+    const rawPageBodyByPath = /* @__PURE__ */ new Map();
     for (const raw of scan.data.raw) {
       const text = await readPage(raw);
       const split = splitFrontmatter(text);
       if (!split.ok) continue;
+      rawPageBodyByPath.set(raw.relPath, split.data.body);
       if (/^source_url:\s*file:\/\//m.test(split.data.rawFrontmatter)) {
-        fileSourceUrlFlags.push(raw.relPath);
+        fileSourceUrlFlags.add(raw.relPath);
+        fileSourceUrlFrontmatterFlags.add(raw.relPath);
       }
       const sourceUrl = split.data.rawFrontmatter.match(/^source_url:\s*(.+)$/m)?.[1]?.trim().replace(/^["']|["']$/g, "") ?? "";
       const assessment = assessSourceIdentity({
@@ -3222,7 +3244,26 @@ async function runLint(input) {
         });
       }
     }
-    if (fileSourceUrlFlags.length > 0) buckets.file_source_url = fileSourceUrlFlags;
+    const canonicalSourcePages = [
+      ...scan.data.raw,
+      ...scan.data.typedKnowledge,
+      ...scan.data.compound,
+      ...scan.data.workItems
+    ];
+    for (const page of canonicalSourcePages) {
+      if (!shouldCheckCanonicalLocalSourceAssertion(page)) continue;
+      let body = rawPageBodyByPath.get(page.relPath);
+      if (body === void 0) {
+        const text = await readPage(page);
+        const split = splitFrontmatter(text);
+        if (!split.ok) continue;
+        body = split.data.body;
+      }
+      if (hasCanonicalLocalSourceAssertion(body)) {
+        fileSourceUrlFlags.add(page.relPath);
+      }
+    }
+    if (fileSourceUrlFlags.size > 0) buckets.file_source_url = [...fileSourceUrlFlags];
     if (rawIdentityConflicts.length > 0) buckets.raw_source_identity_conflict = rawIdentityConflicts;
     const legacyPages = [];
     const orphanedPages = [];
@@ -3697,9 +3738,9 @@ ${newBody}`;
         else delete buckets.wikilink_citation;
       }
     }
-    if (shouldFix("file_source_url") && fileSourceUrlFlags.length > 0) {
+    if (shouldFix("file_source_url") && fileSourceUrlFrontmatterFlags.size > 0) {
       const FILE_FIXED = [];
-      for (const relPath of fileSourceUrlFlags) {
+      for (const relPath of fileSourceUrlFrontmatterFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
           const raw = await readFile12(absPath, "utf8");
@@ -3730,9 +3771,26 @@ ${newBody}`;
       }
       fixed.push(...FILE_FIXED);
       if (FILE_FIXED.length > 0) {
-        const fixedSet = new Set(FILE_FIXED);
-        const remaining = fileSourceUrlFlags.filter((p) => !fixedSet.has(p));
-        if (remaining.length > 0) buckets.file_source_url = remaining;
+        const remaining = new Set(fileSourceUrlFlags);
+        for (const relPath of FILE_FIXED) {
+          try {
+            const page = scan.data.allMarkdown.find((p) => p.relPath === relPath);
+            if (!page) {
+              remaining.delete(relPath);
+              continue;
+            }
+            const text = await readPage(page);
+            const split = splitFrontmatter(text);
+            if (!split.ok) continue;
+            const stillHasFileSourceUrl = /^source_url:\s*file:\/\//m.test(split.data.rawFrontmatter);
+            const stillHasCanonicalBodyAssertion = shouldCheckCanonicalLocalSourceAssertion(page) && hasCanonicalLocalSourceAssertion(split.data.body);
+            if (!stillHasFileSourceUrl && !stillHasCanonicalBodyAssertion) {
+              remaining.delete(relPath);
+            }
+          } catch {
+          }
+        }
+        if (remaining.size > 0) buckets.file_source_url = [...remaining];
         else delete buckets.file_source_url;
       }
     }

package/dist/cli.js

@@ -69,7 +69,7 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-JENSKJP6.js";
+} from "./chunk-6G7RAAOS.js";
 import {
   normalizeDistTag
 } from "./chunk-E6UWZ3S3.js";

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-JENSKJP6.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.30",
+  "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.30",
+  "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.30",
+  "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.30",
+  "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.

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

@@ -18,6 +18,7 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
 1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
 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).
+   - **Portable local-source rule:** follow `using-skillwiki` → Portable Source References. Do not use `source_url: file:///...` as the canonical durable reference; prefer commit-pinned GitHub `blob/<commit>/<path>` when resolvable, else empty `source_url` plus portable repo-relative prose.
 3. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
 5. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
@@ -56,6 +57,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Updating `index.md` or `log.md` before all pages validate.
 - Modifying any existing file in `raw/`.
 - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
+- Writing host-local absolute paths as canonical durable source references (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.
 ## Batch Mode
 When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):

package/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/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.

package/skills/wiki-ingest/SKILL.md

@@ -18,6 +18,7 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
 1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
 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).
+   - **Portable local-source rule:** follow `using-skillwiki` → Portable Source References. Do not use `source_url: file:///...` as the canonical durable reference; prefer commit-pinned GitHub `blob/<commit>/<path>` when resolvable, else empty `source_url` plus portable repo-relative prose.
 3. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
 5. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
@@ -56,6 +57,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Updating `index.md` or `log.md` before all pages validate.
 - Modifying any existing file in `raw/`.
 - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
+- Writing host-local absolute paths as canonical durable source references (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.
 ## Batch Mode
 When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):