skillwiki 0.9.56 → 0.9.58

package/dist/auto-update-bg.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
 import {
   cachePath,
   normalizeDistTag,

package/dist/{chunk-SE5URAJR.js → chunk-NIPZVIHT.js}

@@ -2888,6 +2888,7 @@ function buildCliSurface() {
   syncCmd.command("lock").option("--summary <text>").option("--ttl-minutes <n>").option("--force").option("--wiki <name>");
   syncCmd.command("unlock").option("--force").option("--wiki <name>");
   syncCmd.command("peers").option("--wiki <name>");
+  syncCmd.command("lint-delta").option("--base-ref <ref>").option("--wiki <name>");
   const backupCmd = program.commands.find((c) => c.name() === "backup");
   backupCmd.command("sync").option("--dry-run").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--prune").option("--wiki <name>");
   backupCmd.command("restore").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--target <dir>").option("--wiki <name>");
@@ -4250,6 +4251,159 @@ ${split.data.body}`;
     result: ok(input.summary ? summarizeLintOutput(output, input.examplesLimit) : output)
   };
 }
+function lintIssueFingerprint(bucket, item) {
+  const page = extractIssuePage(item);
+  const detail = normalizeIssueDetail(item);
+  return `${bucket}\0${page}\0${detail}`;
+}
+function extractIssuePage(item) {
+  if (typeof item === "string") {
+    const m = item.match(/^([^:]+?)(?::\s|$)/);
+    return (m?.[1] ?? item).trim();
+  }
+  if (item && typeof item === "object") {
+    const obj = item;
+    for (const key of ["path", "file", "page", "relPath"]) {
+      if (typeof obj[key] === "string") return obj[key];
+    }
+  }
+  return "";
+}
+function normalizeIssueDetail(item) {
+  if (typeof item === "string") {
+    return item.replace(/\s+/g, " ").trim();
+  }
+  try {
+    return JSON.stringify(item, Object.keys(item).sort());
+  } catch {
+    return String(item);
+  }
+}
+function collectLintErrorFingerprints(output) {
+  const fps = /* @__PURE__ */ new Set();
+  for (const bucket of output.by_severity.error) {
+    for (const item of bucket.items) {
+      fps.add(lintIssueFingerprint(bucket.kind, item));
+    }
+  }
+  return fps;
+}
+async function runSyncLintDelta(input) {
+  const { mkdtempSync, rmSync, existsSync: fsExists } = await import("fs");
+  const { join: pathJoin } = await import("path");
+  const { tmpdir } = await import("os");
+  const { execFileSync: execFileSync2 } = await import("child_process");
+  const vault = input.vault;
+  const baseRef = input.baseRef ?? "origin/main";
+  const days = input.days ?? 90;
+  const lines = input.lines ?? 200;
+  const logThreshold = input.logThreshold ?? 500;
+  if (!fsExists(pathJoin(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("NOT_A_GIT_REPO", { path: vault })
+    };
+  }
+  try {
+    execFileSync2("git", ["rev-parse", "--verify", baseRef], {
+      cwd: vault,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch {
+    return {
+      exitCode: ExitCode.LINT_HAS_ERRORS,
+      result: err("LINT_DELTA_BASE_UNAVAILABLE", {
+        baseRef,
+        message: `base ref ${baseRef} does not resolve \u2014 fail closed`
+      })
+    };
+  }
+  const fullLint = await runLint({ vault, days, lines, logThreshold });
+  if (!fullLint.result.ok) {
+    return {
+      exitCode: ExitCode.LINT_HAS_ERRORS,
+      result: err("LINT_DELTA_FULL_FAILED", { detail: fullLint.result })
+    };
+  }
+  const fullOutput = fullLint.result.data;
+  if (!("by_severity" in fullOutput) || !fullOutput.by_severity) {
+    return {
+      exitCode: ExitCode.LINT_HAS_ERRORS,
+      result: err("LINT_DELTA_MALFORMED", { message: "full lint missing by_severity" })
+    };
+  }
+  const fullFps = collectLintErrorFingerprints(fullOutput);
+  const tmpRoot = mkdtempSync(pathJoin(tmpdir(), "skillwiki-lint-delta-"));
+  try {
+    const archive = execFileSync2("git", ["archive", "--format=tar", baseRef], {
+      cwd: vault,
+      stdio: ["pipe", "pipe", "pipe"],
+      maxBuffer: 256 * 1024 * 1024
+    });
+    execFileSync2("tar", ["-xf", "-"], {
+      cwd: tmpRoot,
+      input: archive,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (!fsExists(pathJoin(tmpRoot, "SCHEMA.md"))) {
+    }
+    const baseLint = await runLint({ vault: tmpRoot, days, lines, logThreshold });
+    if (!baseLint.result.ok) {
+      return {
+        exitCode: ExitCode.LINT_HAS_ERRORS,
+        result: err("LINT_DELTA_BASE_LINT_FAILED", {
+          baseRef,
+          detail: baseLint.result
+        })
+      };
+    }
+    const baseOutput = baseLint.result.data;
+    if (!("by_severity" in baseOutput) || !baseOutput.by_severity) {
+      return {
+        exitCode: ExitCode.LINT_HAS_ERRORS,
+        result: err("LINT_DELTA_MALFORMED", { message: "base lint missing by_severity" })
+      };
+    }
+    const baseFps = collectLintErrorFingerprints(baseOutput);
+    const newFps = [];
+    const resolvedFps = [];
+    for (const fp of fullFps) {
+      if (!baseFps.has(fp)) newFps.push(fp);
+    }
+    for (const fp of baseFps) {
+      if (!fullFps.has(fp)) resolvedFps.push(fp);
+    }
+    newFps.sort();
+    resolvedFps.sort();
+    const fullList = [...fullFps].sort();
+    const output = {
+      full_errors: fullFps.size,
+      base_errors: baseFps.size,
+      new_errors: newFps.length,
+      resolved_errors: resolvedFps.length,
+      full_fingerprints: fullList,
+      new_fingerprints: newFps,
+      resolved_fingerprints: resolvedFps,
+      base_ref: baseRef,
+      humanHint: newFps.length > 0 ? `lint delta: ${newFps.length} new error(s) vs ${baseRef} (full=${fullFps.size}, base=${baseFps.size}, resolved=${resolvedFps.length})` : fullFps.size > 0 ? `lint delta: 0 new errors vs ${baseRef}; inherited full_errors=${fullFps.size} (base=${baseFps.size}, resolved=${resolvedFps.length})` : `lint delta: clean (0 errors) vs ${baseRef}`
+    };
+    const exitCode = output.new_errors > 0 ? ExitCode.LINT_HAS_ERRORS : fullLint.exitCode === ExitCode.LINT_HAS_WARNINGS ? ExitCode.LINT_HAS_WARNINGS : ExitCode.OK;
+    return { exitCode, result: ok(output) };
+  } catch (e) {
+    return {
+      exitCode: ExitCode.LINT_HAS_ERRORS,
+      result: err("LINT_DELTA_ARCHIVE_FAILED", {
+        baseRef,
+        message: String(e)
+      })
+    };
+  } finally {
+    try {
+      rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
 
 // src/commands/config.ts
 import { readFile as readFile13 } from "fs/promises";
@@ -9507,6 +9661,7 @@ export {
   fixPathTooLong,
   assessSourceIdentity,
   runLint,
+  runSyncLintDelta,
   configPath,
   runConfigGet,
   runConfigSet,

package/dist/cli.js

@@ -66,6 +66,7 @@ import {
   runQuery,
   runSkillwikiMcpStdio,
   runStale,
+  runSyncLintDelta,
   runTagAudit,
   runTopicMapCheck,
   runValidate,
@@ -76,7 +77,7 @@ import {
   snapshotterAliasForLocalHost,
   splitFrontmatter,
   writeDotenv
-} from "./chunk-SE5URAJR.js";
+} from "./chunk-NIPZVIHT.js";
 import {
   normalizeDistTag,
   readCache,
@@ -3725,15 +3726,51 @@ async function runSyncPush(input) {
       })
     };
   }
-  const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
-  if (lintResult.result.ok && lintResult.result.data.summary.errors > 0) {
-    return {
-      exitCode: ExitCode.LINT_HAS_ERRORS,
-      result: err("LINT_ERRORS_BLOCK_PUSH", {
-        errors: lintResult.result.data.summary.errors,
-        buckets: lintResult.result.data.by_severity.error
-      })
-    };
+  let delta = { full_errors: 0, base_errors: 0, new_errors: 0, resolved_errors: 0 };
+  const preferredBase = git(vault, ["rev-parse", "--verify", "origin/main"]) ? "origin/main" : git(vault, ["rev-parse", "--verify", "origin/HEAD"]) ? "origin/HEAD" : "";
+  if (preferredBase) {
+    const deltaResult = await runSyncLintDelta({ vault, baseRef: preferredBase });
+    if (!deltaResult.result.ok) {
+      return {
+        exitCode: ExitCode.LINT_HAS_ERRORS,
+        result: err("LINT_DELTA_UNAVAILABLE", {
+          message: "lint-delta evidence missing or failed \u2014 fail closed",
+          detail: deltaResult.result
+        })
+      };
+    }
+    delta = deltaResult.result.data;
+    if (delta.new_errors > 0) {
+      return {
+        exitCode: ExitCode.LINT_HAS_ERRORS,
+        result: err("LINT_NEW_ERRORS_BLOCK_PUSH", {
+          full_errors: delta.full_errors,
+          base_errors: delta.base_errors,
+          new_errors: delta.new_errors,
+          resolved_errors: delta.resolved_errors,
+          new_fingerprints: deltaResult.result.data.new_fingerprints
+        })
+      };
+    }
+  } else {
+    const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
+    if (lintResult.result.ok) {
+      const fullErrors = lintResult.result.data.summary.errors;
+      delta = { full_errors: fullErrors, base_errors: 0, new_errors: fullErrors, resolved_errors: 0 };
+      if (fullErrors > 0) {
+        const buckets = "by_severity" in lintResult.result.data ? lintResult.result.data.by_severity.error : [];
+        return {
+          exitCode: ExitCode.LINT_HAS_ERRORS,
+          result: err("LINT_ERRORS_BLOCK_PUSH", {
+            errors: fullErrors,
+            buckets,
+            message: "no origin base ref for delta; absolute lint errors block push"
+          })
+        };
+      }
+    } else {
+      delta = { full_errors: 0, base_errors: 0, new_errors: 0, resolved_errors: 0 };
+    }
   }
   try {
     stageVaultContentChanges(vault);
@@ -3776,6 +3813,7 @@ async function runSyncPush(input) {
       })
     };
   }
+  const inheritedNote = delta.full_errors > 0 ? `; lint full=${delta.full_errors} base=${delta.base_errors} new=${delta.new_errors} resolved=${delta.resolved_errors} (inherited debt only)` : `; lint full=0 new=0`;
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -3783,7 +3821,11 @@ async function runSyncPush(input) {
       commit_message: commitMessage,
       pushed,
       path_fixes: pathFixes,
-      humanHint: `committed and pushed ${dirtyFiles.length} file(s)${pathFixes > 0 ? ` after ${pathFixes} long-path fix(es)` : ""}`
+      lint_full_errors: delta.full_errors,
+      lint_base_errors: delta.base_errors,
+      lint_new_errors: delta.new_errors,
+      lint_resolved_errors: delta.resolved_errors,
+      humanHint: `committed and pushed ${dirtyFiles.length} file(s)${pathFixes > 0 ? ` after ${pathFixes} long-path fix(es)` : ""}${inheritedNote}`
     })
   };
 }
@@ -5498,6 +5540,11 @@ syncCmd.command("peers [vault]").description("list active locks and recent wiki-
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(runSyncPeers({ vault: v.vault, sessionId: getCliSessionId() }));
 });
+syncCmd.command("lint-delta [vault]").description("compare lint errors against a base ref; block only on new errors").option("--base-ref <ref>", "base git ref to compare against", "origin/main").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 runSyncLintDelta({ vault: v.vault, baseRef: opts.baseRef }));
+});
 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);

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-SE5URAJR.js";
+} from "./chunk-NIPZVIHT.js";
 import "./chunk-7I2TPIV5.js";
 
 // src/mcp-entry.ts

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "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.56",
+  "version": "0.9.58",
   "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/README.md

@@ -1,11 +1,22 @@
 # @skillwiki/skills
 
-Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`.
+Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`
+or the Claude/Codex/Antigravity plugin packaging paths.
+
+Current package inventory: **18 skills**.
 
 | Namespace | Skills |
 |---|---|
-| `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit` |
+| `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit`, `wiki-archive`, `wiki-reingest`, `wiki-adapter-prd`, `wiki-add-task`, `wiki-sync`, `wiki-canvas`, `wiki-gate-plan-mode` |
 | `proj-*` | `proj-init`, `proj-work`, `proj-distill`, `proj-decide` |
+| onboarding | `using-skillwiki` |
+
+Verify the live inventory from source:
+
+```bash
+find packages/skills -mindepth 2 -maxdepth 2 -name SKILL.md -print | sort
+bash scripts/verify-manifests.sh
+```
 
 Each top-level skill subdirectory holds one canonical `SKILL.md`. The nested
 `skills/<skill>/SKILL.md` tree mirrors those files for Codex plugin discovery;
@@ -20,3 +31,6 @@ Codex-specific hook files. That root exposes `hooks/hooks-codex.json` and
 Run `npm run materialize:plugins` from the repository root after changing
 canonical skill, agent, or hook assets. Run
 `npm run materialize:plugins:check` for read-only drift detection.
+
+The sibling `vault-sync` plugin ships six additional operational skills under
+`packages/vault-sync/skills/` and is packaged separately from this skill set.

package/skills/package.json

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

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

@@ -44,8 +44,8 @@ On every invocation, count `wiki-sync:*` stashes older than 24 hours via `skillw
 
 ### Push workflow
 4. If vault is dirty, ask the user to review uncommitted changes before proceeding.
-5. Run `skillwiki lint <vault>`. If errors exist, stop and report — do not push lint errors to remote.
-6. If lint passes (errors = 0), stage and commit:
+5. Run `skillwiki sync lint-delta <vault> --base-ref origin/main`. Block only when `new_errors > 0`. Report full/base/new/resolved. Malformed delta evidence fails closed — do not push.
+6. If lint-delta allows (new_errors = 0), stage and commit:
    - `git -C <vault> add -A`
    - `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
 7. Run `git -C <vault> push origin HEAD`. Report result.
@@ -62,7 +62,7 @@ On every invocation, count `wiki-sync:*` stashes older than 24 hours via `skillw
     MSG="wiki-sync:${SESSION_ID}:${CWD_HASH}:${ISO_TS}:pre-pull"
     git -C "$VAULT" stash push -m "$MSG"
     ```
-11. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
+11. Prefer the canonical pull helper (`wiki-pull-with-auto-resolve.sh` / vault-presync `--execute`) so stale-clean rebase state uses recovery-ref + `rebase --quit`, active rebases fail closed, and only fully materialized commits are dropped. If invoking git directly: `git -C <vault> pull --rebase origin HEAD`. Report result.
 12. If a stash was created, pop it: `git -C <vault> stash pop`.
 13. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
 14. Run `skillwiki lint <vault>` after pull to verify vault integrity.
@@ -240,3 +240,20 @@ bash ~/.hermes/scripts/wiki-snapshot.sh  # Re-sync fresh
 - Modifying files in `raw/` to resolve conflicts (N9 — archive and re-ingest instead).
 - Stashing without the `wiki-sync:...` name format (breaks peer detection).
 - Force-deleting a peer's lockfile (use `--force` only if peer is confirmed dead).
+
+## Convergence safeguards (2026-07-11)
+
+### Rebase-state classification
+- `stale-clean`: recovery ref at tip + `git rebase --quit` (preserves advanced tip; never abort-reset to orig-head).
+- `active` (REBASE_HEAD / UU paths): leave untouched; fail closed.
+- Recovery refs live under `refs/vault-sync/recovery/<UTC timestamp>`.
+
+### Materialized-commit proof
+Drop a local commit from rebase only when every path is proven present on the target ref (exact blobs; byte-identical added `## ` log sections). Partial/raw/rename mismatches retain or stop.
+
+### Lint-delta fail-closed
+- Fingerprints: `<bucket>\0<page>\0<normalized-detail>`
+- CLI: `skillwiki sync lint-delta <vault> --base-ref origin/main`
+- Block publication only when `new_errors > 0`; inherited full debt remains visible.
+- Missing/malformed delta evidence blocks (never silent lint skip).
+

package/skills/wiki-sync/SKILL.md

@@ -44,8 +44,8 @@ On every invocation, count `wiki-sync:*` stashes older than 24 hours via `skillw
 
 ### Push workflow
 4. If vault is dirty, ask the user to review uncommitted changes before proceeding.
-5. Run `skillwiki lint <vault>`. If errors exist, stop and report — do not push lint errors to remote.
-6. If lint passes (errors = 0), stage and commit:
+5. Run `skillwiki sync lint-delta <vault> --base-ref origin/main`. Block only when `new_errors > 0`. Report full/base/new/resolved. Malformed delta evidence fails closed — do not push.
+6. If lint-delta allows (new_errors = 0), stage and commit:
    - `git -C <vault> add -A`
    - `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
 7. Run `git -C <vault> push origin HEAD`. Report result.
@@ -62,7 +62,7 @@ On every invocation, count `wiki-sync:*` stashes older than 24 hours via `skillw
     MSG="wiki-sync:${SESSION_ID}:${CWD_HASH}:${ISO_TS}:pre-pull"
     git -C "$VAULT" stash push -m "$MSG"
     ```
-11. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
+11. Prefer the canonical pull helper (`wiki-pull-with-auto-resolve.sh` / vault-presync `--execute`) so stale-clean rebase state uses recovery-ref + `rebase --quit`, active rebases fail closed, and only fully materialized commits are dropped. If invoking git directly: `git -C <vault> pull --rebase origin HEAD`. Report result.
 12. If a stash was created, pop it: `git -C <vault> stash pop`.
 13. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
 14. Run `skillwiki lint <vault>` after pull to verify vault integrity.
@@ -240,3 +240,20 @@ bash ~/.hermes/scripts/wiki-snapshot.sh  # Re-sync fresh
 - Modifying files in `raw/` to resolve conflicts (N9 — archive and re-ingest instead).
 - Stashing without the `wiki-sync:...` name format (breaks peer detection).
 - Force-deleting a peer's lockfile (use `--force` only if peer is confirmed dead).
+
+## Convergence safeguards (2026-07-11)
+
+### Rebase-state classification
+- `stale-clean`: recovery ref at tip + `git rebase --quit` (preserves advanced tip; never abort-reset to orig-head).
+- `active` (REBASE_HEAD / UU paths): leave untouched; fail closed.
+- Recovery refs live under `refs/vault-sync/recovery/<UTC timestamp>`.
+
+### Materialized-commit proof
+Drop a local commit from rebase only when every path is proven present on the target ref (exact blobs; byte-identical added `## ` log sections). Partial/raw/rename mismatches retain or stop.
+
+### Lint-delta fail-closed
+- Fingerprints: `<bucket>\0<page>\0<normalized-detail>`
+- CLI: `skillwiki sync lint-delta <vault> --base-ref origin/main`
+- Block publication only when `new_errors > 0`; inherited full debt remains visible.
+- Missing/malformed delta evidence blocks (never silent lint skip).
+