skillwiki 0.10.12 → 0.10.13

package/dist/{chunk-TYN2IHBY.js → chunk-E3PMAHS3.js}

@@ -702,14 +702,17 @@ function isWorktreeClean(vault) {
   const porcelain = git(vault, ["status", "--porcelain"]);
   return !porcelain || porcelain.trim() === "";
 }
-function canSupersedeJournal(vault, fields) {
-  if (hasUnmergedPaths(vault).length > 0) return false;
-  if (hasActiveGitSequencer(vault)) return false;
-  if (!isWorktreeClean(vault)) return false;
-  const target = fields.target_oid?.trim();
-  if (!target) return false;
+function journalSupersedeHead(vault, requireClean) {
+  if (hasUnmergedPaths(vault).length > 0 || hasActiveGitSequencer(vault) || requireClean && !isWorktreeClean(vault)) {
+    return null;
+  }
   const head = git(vault, ["rev-parse", "HEAD"]);
+  return head || null;
+}
+function canSupersedeJournalInContext(vault, fields, head) {
   if (!head) return false;
+  const target = fields.target_oid?.trim();
+  if (!target) return false;
   return gitMergeBaseIsAncestor(vault, target, head);
 }
 function gitMergeBaseIsAncestor(vault, ancestor, tip) {
@@ -733,14 +736,12 @@ function markJournalSuperseded(vault, opId, fields, by) {
 }
 function supersedeStaleReviewRequiredJournals(vault, opts = {}) {
   const by = opts.by ?? "skillwiki-preflight";
+  const requireClean = opts.requireClean !== false;
   const superseded = [];
   const skipped = [];
-  if (hasUnmergedPaths(vault).length > 0 || hasActiveGitSequencer(vault) || !isWorktreeClean(vault)) {
-    for (const { opId } of listReviewRequiredOps(vault)) skipped.push(opId);
-    return { superseded, skipped };
-  }
+  const head = journalSupersedeHead(vault, requireClean);
   for (const { opId, fields } of listReviewRequiredOps(vault)) {
-    if (!canSupersedeJournal(vault, fields)) {
+    if (!canSupersedeJournalInContext(vault, fields, head)) {
       skipped.push(opId);
       continue;
     }

package/dist/{chunk-3ZVZ2YEE.js → chunk-IIUMTKKA.js}

@@ -8,7 +8,7 @@ import {
   loadFleetManifestAndHost,
   runVaultSyncPullHelper,
   supersedeStaleReviewRequiredJournals
-} from "./chunk-TYN2IHBY.js";
+} from "./chunk-E3PMAHS3.js";
 import {
   ExitCode,
   err,
@@ -163,7 +163,10 @@ function preflightBlocker(vault) {
   if (hasActiveGitSequencer(vault)) {
     return { reason: "git-operation-in-progress" };
   }
-  supersedeStaleReviewRequiredJournals(vault, { by: "skillwiki-managed-write-preflight" });
+  supersedeStaleReviewRequiredJournals(vault, {
+    by: "skillwiki-managed-write-preflight",
+    requireClean: false
+  });
   const op = findReviewRequiredOp(vault);
   if (op) return { reason: "review-required", operation_id: op };
   return null;

package/dist/{chunk-YYWGP7DN.js → chunk-X2CPXF4T.js}

@@ -33,7 +33,7 @@ import {
   satelliteGateFromFleetLoad,
   snapshotterAliasForLocalHost,
   writeDotenv
-} from "./chunk-TYN2IHBY.js";
+} from "./chunk-E3PMAHS3.js";
 import {
   CompoundSchema,
   ExitCode,

package/dist/cli.js

@@ -82,7 +82,7 @@ import {
   upsertIndexEntry,
   validateLogEvent,
   writeLogEvent
-} from "./chunk-YYWGP7DN.js";
+} from "./chunk-X2CPXF4T.js";
 import {
   normalizeDistTag,
   readCache,
@@ -110,7 +110,7 @@ import {
   releaseManagedWriteLock,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-3ZVZ2YEE.js";
+} from "./chunk-IIUMTKKA.js";
 import {
   FLEET_REL_PATH,
   git,
@@ -132,7 +132,7 @@ import {
   snapshotterAliasForLocalHost,
   supersedeStaleReviewRequiredJournals,
   writeDotenv
-} from "./chunk-TYN2IHBY.js";
+} from "./chunk-E3PMAHS3.js";
 import {
   ExitCode,
   MetaSchema,
@@ -2247,6 +2247,9 @@ function writeWorkJournal(vault, opId, fields) {
   writeFileSync3(tmp, body, "utf8");
   renameSync(tmp, path);
 }
+var DEFAULT_DEPS = {
+  writeEvidenceText: atomicWriteText
+};
 var PHASE_ORDER = ["validate", "evidence", "log", "projection", "commit", "done"];
 function resolveWorkDir(vault, workItem) {
   const rel = normalizeWorkItemRel(workItem);
@@ -2301,7 +2304,7 @@ ${body}`);
 async function setStatusCompleted(filePath) {
   return patchFrontmatterStatus(filePath);
 }
-async function writeEvidence(workDir, opId, phases) {
+async function writeEvidence(workDir, opId, phases, writeText) {
   const path = join16(workDir, "evidence.md");
   const body = [
     "---",
@@ -2317,7 +2320,7 @@ async function writeEvidence(workDir, opId, phases) {
     `- completed_at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
     ""
   ].join("\n");
-  return atomicWriteText(path, body);
+  return writeText(path, body);
 }
 async function markPlanComplete(workDir) {
   const planPath = join16(workDir, "plan.md");
@@ -2330,7 +2333,7 @@ function writeFailure(stage, result) {
     result: result.ok ? err("WRITE_FAILED", { stage, message: "unexpected ok" }) : result
   };
 }
-async function runWorkComplete(input) {
+async function runWorkComplete(input, deps = DEFAULT_DEPS) {
   const workDirResult = resolveWorkDir(input.vault, input.workItem);
   if (!workDirResult.ok) {
     return {
@@ -2411,7 +2414,12 @@ async function runWorkComplete(input) {
       if (!statusWrite.ok) return writeFailure("evidence-spec", statusWrite);
       const planWrite = await markPlanComplete(workDir);
       if (!planWrite.ok) return writeFailure("evidence-plan", planWrite);
-      const evidenceWrite = await writeEvidence(workDir, opId, completedPhases);
+      const evidenceWrite = await writeEvidence(
+        workDir,
+        opId,
+        completedPhases,
+        deps.writeEvidenceText
+      );
       if (!evidenceWrite.ok) return writeFailure("evidence", evidenceWrite);
       if (input.failAfter === "evidence") {
         throw new Error("simulated failure after evidence");
@@ -2442,7 +2450,12 @@ async function runWorkComplete(input) {
     }
     if (phaseIndex(phase) <= phaseIndex("projection")) {
       if (!existsSync4(join16(workDir, "evidence.md"))) {
-        const evidenceWrite = await writeEvidence(workDir, opId, completedPhases);
+        const evidenceWrite = await writeEvidence(
+          workDir,
+          opId,
+          completedPhases,
+          deps.writeEvidenceText
+        );
         if (!evidenceWrite.ok) return writeFailure("projection-evidence", evidenceWrite);
       }
       const finalCheck = await runWorkValidate({
@@ -4698,7 +4711,7 @@ import { createHash as createHash4 } from "crypto";
 import { realpathSync } from "fs";
 import { readFile as readFile12 } from "fs/promises";
 import { join as join26, resolve as resolve3 } from "path";
-var DEFAULT_DEPS = {
+var DEFAULT_DEPS2 = {
   afterStage: async () => void 0,
   preflight: (input) => runManagedWritePreflight(input)
 };
@@ -5018,7 +5031,7 @@ async function previewPreparedPagePublication(input, vault) {
     true
   );
 }
-async function publishPreparedPage(input, vault, deps = DEFAULT_DEPS) {
+async function publishPreparedPage(input, vault, deps = DEFAULT_DEPS2) {
   const managed = acquireManagedWriteLock(vault, `page publish ${input.page.target}`);
   if (!managed.ok) return { exitCode: errorExitCode(managed.error), result: managed };
   try {
@@ -5173,7 +5186,7 @@ async function publishPreparedPage(input, vault, deps = DEFAULT_DEPS) {
     releaseManagedWriteLock(managed.data);
   }
 }
-async function runPagePublish(input, deps = DEFAULT_DEPS) {
+async function runPagePublish(input, deps = DEFAULT_DEPS2) {
   const prepared = await preparePagePublication(input);
   if (!prepared.ok) return { exitCode: errorExitCode(prepared.error), result: prepared };
   if (!input.write) return previewPreparedPagePublication(prepared.data, input.vault);
@@ -7484,7 +7497,7 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (dirty) {
     return emit(dirty, void 0, { postCommit: false });
   }
-  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-7TWSEZJZ.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-4SWWFT75.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,

package/dist/{managed-write-preflight-7TWSEZJZ.js → managed-write-preflight-4SWWFT75.js}

@@ -2,8 +2,8 @@
 import {
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-3ZVZ2YEE.js";
-import "./chunk-TYN2IHBY.js";
+} from "./chunk-IIUMTKKA.js";
+import "./chunk-E3PMAHS3.js";
 import "./chunk-C5OLZRRM.js";
 export {
   runManagedWritePreflight,

package/dist/skillwiki-mcp.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-YYWGP7DN.js";
+} from "./chunk-X2CPXF4T.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-NMUYMNNB.js";
-import "./chunk-TYN2IHBY.js";
+import "./chunk-E3PMAHS3.js";
 import "./chunk-C5OLZRRM.js";
 
 // src/mcp-entry.ts

package/dist/vault-sync/scripts/lib/git-operation-journal.sh

@@ -38,24 +38,40 @@ vault_sync_op_set_field() {
 vault_sync_op_set_fields() {
   local repo="$1" op_id="$2"
   shift 2
-  local file tmp
+  local file tmp updates source
   file="$(vault_sync_op_journal_path "$repo" "$op_id")" || return 1
   tmp="$(mktemp)" || return 1
-  if [ -f "$file" ]; then
-    cp "$file" "$tmp" || { rm -f "$tmp"; return 1; }
-  else
-    : >"$tmp"
-  fi
+  updates="$(mktemp)" || { rm -f "$tmp"; return 1; }
   while [ "$#" -ge 2 ]; do
-    awk -F= -v k="$1" -v v="$2" '
-      BEGIN{found=0}
-      $1==k {print k"="v; found=1; next}
-      {print}
-      END{if(!found) print k"="v}
-    ' "$tmp" >"${tmp}.new" || { rm -f "$tmp" "${tmp}.new"; return 1; }
-    mv "${tmp}.new" "$tmp"
+    printf '%s=%s\n' "$1" "$2" >>"$updates" || { rm -f "$tmp" "$updates"; return 1; }
     shift 2
   done
+  source="$file"
+  [ -f "$source" ] || source=/dev/null
+  awk -F= '
+    FNR==NR {
+      key=$1
+      if (!(key in replacement)) order[++count]=key
+      replacement[key]=substr($0, index($0,"=")+1)
+      next
+    }
+    {
+      key=$1
+      if (key in replacement) {
+        print key"="replacement[key]
+        seen[key]=1
+        next
+      }
+      print
+    }
+    END {
+      for (i=1; i<=count; i++) {
+        key=order[i]
+        if (!(key in seen)) print key"="replacement[key]
+      }
+    }
+  ' "$updates" "$source" >"$tmp" || { rm -f "$tmp" "$updates"; return 1; }
+  rm -f "$updates"
   mv "$tmp" "$file"
 }
 
@@ -160,6 +176,83 @@ vault_sync_op_find_review_required() {
   return 1
 }
 
+# Mark one obsolete review-required handoff complete while preserving its audit
+# trail. Caller must establish that no live owner is mutating the journal.
+vault_sync_op_mark_superseded_stale_review_required() {
+  local repo="$1" op_id="$2" by="${3:-vault-sync-managed-preflight}"
+  local reason="$4" prior_reason="$5" now
+  if [ -z "$prior_reason" ] && [ -n "$reason" ] && [ "$reason" != "superseded-stale-review-required" ]; then
+    prior_reason="$reason"
+  fi
+  now="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date +%Y-%m-%dT%H:%M:%S)"
+  vault_sync_op_set_fields "$repo" "$op_id" \
+    "phase" "complete" \
+    "handoff" "1" \
+    "reason" "superseded-stale-review-required" \
+    "prior_reason" "$prior_reason" \
+    "superseded_at" "$now" \
+    "cleared_by" "$by" \
+    "cleared_reason" "operator-or-preflight $now"
+}
+
+# Auto-supersede review-required handoffs whose target is already an ancestor
+# of HEAD. Unrelated dirty WIP is preserved; active sequencers and unmerged
+# paths fail closed. Returns nonzero while any applicable handoff remains open.
+vault_sync_op_supersede_stale_review_required() {
+  local repo="$1" by="${2:-vault-sync-managed-preflight}"
+  local current_git_dir git_dir unmerged jdir jf op_id phase handoff journal_git_dir target unresolved
+  local reason prior_reason key value
+
+  current_git_dir="$(git -C "$repo" rev-parse --absolute-git-dir 2>/dev/null)" || return 1
+  git_dir="$current_git_dir"
+  if [ -d "$git_dir/rebase-merge" ] || [ -d "$git_dir/rebase-apply" ] \
+    || [ -f "$git_dir/MERGE_HEAD" ] || [ -f "$git_dir/CHERRY_PICK_HEAD" ] \
+    || [ -f "$git_dir/REVERT_HEAD" ]; then
+    return 1
+  fi
+  unmerged="$(git -C "$repo" ls-files -u 2>/dev/null | head -1 || true)"
+  [ -z "$unmerged" ] || return 1
+
+  jdir="$(vault_sync_op_journal_dir "$repo")" || return 1
+  [ -d "$jdir" ] || return 0
+  unresolved=""
+  for jf in "$jdir"/*.env; do
+    [ -f "$jf" ] || continue
+    op_id="$(basename "$jf" .env)"
+    phase=""
+    handoff=""
+    journal_git_dir=""
+    target=""
+    reason=""
+    prior_reason=""
+    while IFS='=' read -r key value; do
+      case "$key" in
+        phase) phase="$value" ;;
+        handoff) handoff="$value" ;;
+        worktree_git_dir) journal_git_dir="$value" ;;
+        target_oid) target="$value" ;;
+        reason) reason="$value" ;;
+        prior_reason) prior_reason="$value" ;;
+      esac
+    done <"$jf"
+    [ "$phase" = "review-required" ] && [ "$handoff" = "1" ] || continue
+    if [ -n "$journal_git_dir" ] && [ "$journal_git_dir" != "$current_git_dir" ]; then
+      continue
+    fi
+    if [ -z "$target" ]; then
+      [ -n "$unresolved" ] || unresolved="$op_id"
+      continue
+    fi
+    if git -C "$repo" merge-base --is-ancestor "$target" HEAD 2>/dev/null; then
+      vault_sync_op_mark_superseded_stale_review_required \
+        "$repo" "$op_id" "$by" "$reason" "$prior_reason" || return 1
+    else
+      [ -n "$unresolved" ] || unresolved="$op_id"
+    fi
+  done
+  [ -z "$unresolved" ]
+}
+
 vault_sync_op_preflight_blocker() {
   local repo="$1" unmerged op_id git_dir
   unmerged="$(git -C "$repo" diff --name-only --diff-filter=U 2>/dev/null || true)"

package/dist/vault-sync/scripts/lib/managed-write-lock.sh

@@ -62,7 +62,7 @@ vault_sync_managed_lock_safe_to_reclaim() {
 
   # Never reclaim during an active/leftover sequencer.
   if [ -d "$git_dir/rebase-merge" ] || [ -d "$git_dir/rebase-apply" ] \
-    || [ -d "$git_dir/MERGE_HEAD" ] || [ -f "$git_dir/CHERRY_PICK_HEAD" ] \
+    || [ -f "$git_dir/MERGE_HEAD" ] || [ -f "$git_dir/CHERRY_PICK_HEAD" ] \
     || [ -f "$git_dir/REVERT_HEAD" ]; then
     return 1
   fi
@@ -72,13 +72,16 @@ vault_sync_managed_lock_safe_to_reclaim() {
     return 1
   fi
 
-  # When journal helpers are loaded, refuse reclaim while review-required handoff
-  # journals exist. Standalone lock tests may not source the journal library.
-  if command -v vault_sync_op_find_review_required >/dev/null 2>&1; then
+  # When journal helpers are loaded, a dead owner may close handoffs whose
+  # target is already in HEAD, then continue reclaim in this same acquire.
+  # Live owners never reach this function; active sequencers/unmerged paths
+  # already failed closed above. Any unresolved handoff still blocks reclaim.
+  if command -v vault_sync_op_supersede_stale_review_required >/dev/null 2>&1; then
+    vault_sync_op_supersede_stale_review_required \
+      "$repo" "vault-sync-managed-lock-reclaim" 2>/dev/null || return 1
+  elif command -v vault_sync_op_find_review_required >/dev/null 2>&1; then
     review_op="$(vault_sync_op_find_review_required "$repo" 2>/dev/null || true)"
-    if [ -n "$review_op" ]; then
-      return 1
-    fi
+    [ -z "$review_op" ] || return 1
   fi
 
   return 0

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.12",
+  "version": "0.10.13",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 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.10.12",
+  "version": "0.10.13",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 19 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.10.12",
+  "version": "0.10.13",
   "private": true,
   "files": [
     "wiki-*",

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

@@ -86,7 +86,7 @@ After upgrading to skillwiki **≥0.10.1** (or when managed write fails):
 
 1. Run `skillwiki doctor` — checks `vault_sync_pull_helper` and `vault_sync_review_required_journals`.
 2. If pull helper is missing: install `skillwiki@0.10.1+` (helper must resolve from `dist/vault-sync/scripts/`) and/or redeploy vault-sync host install. Last-resort override: `SKILLWIKI_VAULT_SYNC_PULL_HELPER` pointing at `wiki-pull-with-auto-resolve.sh` under host vault-sync `bin/` (macOS Application Support or Linux `~/.local/share/vault-sync/bin`).
-3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Preflight also auto-supersedes stale handoffs when criteria match; do not force-clear during active rebase/unmerged state.
+3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Managed preflight automatically supersedes a handoff when its `target_oid` is already an ancestor of `HEAD` and Git has no active sequencer or unmerged paths; unrelated dirty WIP is preserved. When the same incident also left a dead-owner managed-write lock, that preflight reclaims it with a recovery record in the same invocation. Live owners, active sequencers/unmerged paths, missing/non-ancestor targets, and remaining review-required journals still fail closed.
 4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
 
 Also mirror these pointers in vault-presync / vault-sync-status skills when operating pull/push.

package/skills/using-skillwiki/SKILL.md

@@ -86,7 +86,7 @@ After upgrading to skillwiki **≥0.10.1** (or when managed write fails):
 
 1. Run `skillwiki doctor` — checks `vault_sync_pull_helper` and `vault_sync_review_required_journals`.
 2. If pull helper is missing: install `skillwiki@0.10.1+` (helper must resolve from `dist/vault-sync/scripts/`) and/or redeploy vault-sync host install. Last-resort override: `SKILLWIKI_VAULT_SYNC_PULL_HELPER` pointing at `wiki-pull-with-auto-resolve.sh` under host vault-sync `bin/` (macOS Application Support or Linux `~/.local/share/vault-sync/bin`).
-3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Preflight also auto-supersedes stale handoffs when criteria match; do not force-clear during active rebase/unmerged state.
+3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Managed preflight automatically supersedes a handoff when its `target_oid` is already an ancestor of `HEAD` and Git has no active sequencer or unmerged paths; unrelated dirty WIP is preserved. When the same incident also left a dead-owner managed-write lock, that preflight reclaims it with a recovery record in the same invocation. Live owners, active sequencers/unmerged paths, missing/non-ancestor targets, and remaining review-required journals still fail closed.
 4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
 
 Also mirror these pointers in vault-presync / vault-sync-status skills when operating pull/push.