skillwiki 0.10.12 → 0.10.14

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

@@ -2,8 +2,8 @@
 import {
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-3ZVZ2YEE.js";
-import "./chunk-TYN2IHBY.js";
+} from "./chunk-UJLSUJB6.js";
+import "./chunk-OWPQJOFG.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-2AOOMDZ7.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-NMUYMNNB.js";
-import "./chunk-TYN2IHBY.js";
+import "./chunk-OWPQJOFG.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/dist/vault-sync/scripts/wiki-snapshot.sh

@@ -309,6 +309,18 @@ log() {
     echo "$(date '+%Y-%m-%d %H:%M:%S') $1" | tee -a "$LOG_FILE"
 }
 
+# Emit the canonical snapshot-completion terminal record (v0.10.14).
+# One stable machine-parseable line written for both pushed and no-change
+# success outcomes. Failure paths must never call this.
+#   SNAPSHOT_COMPLETE schema=v1 outcome=<pushed|no-change> result=success ts=<ISO> head=<oid> origin=<oid|unknown>
+emit_snapshot_complete() {
+    local outcome="$1"
+    local head_oid origin_oid
+    head_oid="$(git -C "$SNAPSHOT_WORKTREE" rev-parse HEAD 2>/dev/null || echo unknown)"
+    origin_oid="$(git -C "$SNAPSHOT_WORKTREE" rev-parse --verify -q origin/main 2>/dev/null || echo unknown)"
+    log "SNAPSHOT_COMPLETE schema=v1 outcome=${outcome} result=success ts=$(date -u +%Y-%m-%dT%H:%M:%SZ) head=${head_oid} origin=${origin_oid}"
+}
+
 validate_tombstone_prune_cap() {
     case "$MAX_TOMBSTONE_PRUNES" in
         ''|*[!0-9]*)
@@ -731,6 +743,7 @@ fi
 # Check for changes
 if [ -z "$(git status --porcelain)" ]; then
     log "No changes to commit"
+    emit_snapshot_complete "no-change"
     exit 0
 fi
 
@@ -807,6 +820,7 @@ done
 if [ "$PUSH_SUCCESS" = true ]; then
     log "Push successful"
     log "Status: complete"
+    emit_snapshot_complete "pushed"
     exit 0
 else
     log "ERROR: Push failed after $PUSH_RETRIES attempts"

package/package.json

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

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

@@ -86,8 +86,9 @@ 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.
-4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+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. **Protected snapshotter stale-journal cleanup (v0.10.14+):** On a known protected snapshotter (sg01) where `sync journal clear-stale` is blocked by `PROTECTED_SNAPSHOTTER_WRITE_BLOCKED`, use the attended one-shot maintenance authority instead: `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --dry-run --reason "<operator reason>"` to produce a state-bound approval ID, then `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --approve <id> --reason "<same reason>"` on an attended TTY to execute. This requires the exact configured snapshot worktree, the production snapshot flock, and recomputes the plan under the flock; it is the only allowlisted mutation across the protected boundary. No generic force flag or env bypass exists.
+5. 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,8 +86,9 @@ 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.
-4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+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. **Protected snapshotter stale-journal cleanup (v0.10.14+):** On a known protected snapshotter (sg01) where `sync journal clear-stale` is blocked by `PROTECTED_SNAPSHOTTER_WRITE_BLOCKED`, use the attended one-shot maintenance authority instead: `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --dry-run --reason "<operator reason>"` to produce a state-bound approval ID, then `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --approve <id> --reason "<same reason>"` on an attended TTY to execute. This requires the exact configured snapshot worktree, the production snapshot flock, and recomputes the plan under the flock; it is the only allowlisted mutation across the protected boundary. No generic force flag or env bypass exists.
+5. 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.