skillwiki 0.9.63 → 0.10.0

package/dist/vault-sync/scripts/wiki-snapshot.sh

@@ -0,0 +1,587 @@
+#!/bin/bash
+# wiki-snapshot.sh — Linux-only S3 → git snapshot/promotion job.
+#
+# Source-of-truth: this is the canonical vault-sync copy. The deployed copy on
+# sg01 lives under /root/.local/share/vault-sync/bin; Hermes is not part of the
+# production snapshot path. See work item:
+#   projects/llm-wiki/work/2026-05-25-vault-sync-plugin-scaffold/
+#
+# Origin: migrated 2026-05-25 from sg01 wiki-snapshot-v3.sh (sha256:
+#   037b05ddb6b47e377c3ef493e69730bc3ff3e3ccaa51d56edb7027091582f383).
+#
+# Hard Rule (NON-NEGOTIABLE):
+#   The --max-delete 10 guard in RCLONE_OPTS MUST be preserved.
+#   Without it, momentary S3 inconsistency mass-deletes files from GitHub.
+#   Reference: raw/transcripts/2026-05-23-bug-sg01-snapshot-destructive-rclone-sync.md
+#
+# Single-writer-git invariant: only ONE host per vault remote may run this.
+#   sg01 is the current snapshotter (role: snapshotter in fleet.yaml).
+#   Running on a second host violates the authority model.
+
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -n "${GIT_DIR:-}" ]; then
+    echo "[wiki-snapshot] WARNING: ignoring exported GIT_DIR; use WIKI_GIT_WORKTREE for the snapshot worktree" >&2
+    unset GIT_DIR
+fi
+
+# Source platform.sh — handles both dev (scripts/lib/) and deployed (lib/) layouts
+if [ -f "$SCRIPT_DIR/lib/platform.sh" ]; then
+    source "$SCRIPT_DIR/lib/platform.sh"
+elif [ -f "$SCRIPT_DIR/scripts/lib/platform.sh" ]; then
+    source "$SCRIPT_DIR/scripts/lib/platform.sh"
+elif [ -f "$SCRIPT_DIR/../../scripts/lib/platform.sh" ]; then
+    source "$SCRIPT_DIR/../../scripts/lib/platform.sh"
+fi
+platform_detect_os
+
+if [ -f "$SCRIPT_DIR/lib/git-case.sh" ]; then
+    source "$SCRIPT_DIR/lib/git-case.sh"
+elif [ -f "$SCRIPT_DIR/scripts/lib/git-case.sh" ]; then
+    source "$SCRIPT_DIR/scripts/lib/git-case.sh"
+elif [ -f "$SCRIPT_DIR/../../scripts/lib/git-case.sh" ]; then
+    source "$SCRIPT_DIR/../../scripts/lib/git-case.sh"
+fi
+
+if [ -f "$SCRIPT_DIR/lib/conflict-markers.sh" ]; then
+    source "$SCRIPT_DIR/lib/conflict-markers.sh"
+elif [ -f "$SCRIPT_DIR/scripts/lib/conflict-markers.sh" ]; then
+    source "$SCRIPT_DIR/scripts/lib/conflict-markers.sh"
+elif [ -f "$SCRIPT_DIR/../../scripts/lib/conflict-markers.sh" ]; then
+    source "$SCRIPT_DIR/../../scripts/lib/conflict-markers.sh"
+fi
+
+if [ -f "$SCRIPT_DIR/lib/delete-intent.sh" ]; then
+    source "$SCRIPT_DIR/lib/delete-intent.sh"
+elif [ -f "$SCRIPT_DIR/scripts/lib/delete-intent.sh" ]; then
+    source "$SCRIPT_DIR/scripts/lib/delete-intent.sh"
+elif [ -f "$SCRIPT_DIR/../../scripts/lib/delete-intent.sh" ]; then
+    source "$SCRIPT_DIR/../../scripts/lib/delete-intent.sh"
+fi
+
+if ! command -v vault_sync_scan_conflict_markers >/dev/null 2>&1; then
+    echo "[wiki-snapshot] ERROR: conflict-marker helper unavailable; refusing to run." >&2
+    exit 1
+fi
+
+# ── Guard: Linux-only operation ────────────────────────────
+platform_require linux
+
+# ── Path configuration (env-overridable for plugin portability) ─
+WIKI_DIR="${WIKI_DIR:-/root/wiki}"
+SNAPSHOT_WORKTREE="${WIKI_GIT_WORKTREE:-${SNAPSHOT_WORKTREE:-/root/wiki-git}}"
+LOCK_FILE="${WIKI_SNAPSHOT_LOCK:-/var/lock/wiki-snapshot.lock}"
+DEFAULT_LOG_DIR="$(platform_log_dir)"
+LOG_FILE="${WIKI_SNAPSHOT_LOG:-$DEFAULT_LOG_DIR/wiki-snapshot.log}"
+CLOUD_REMOTE="${CLOUD_REMOTE:-cloud:cloud/wiki}"
+REPAIR_SCRIPT="${WIKI_GIT_REPAIR_SCRIPT:-$SCRIPT_DIR/wiki-git-repair-v3.sh}"
+MAX_S3_ONLY_NOTES="${WIKI_SNAPSHOT_MAX_S3_ONLY_NOTES:-200}"
+DATE=$(date +%Y%m%d_%H%M%S)
+RCLONE_LOG="/tmp/rclone-${DATE}.log"
+SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT=0
+
+fetch_origin_main_ref() {
+    # The snapshot guards read origin/main directly. Use an explicit destination
+    # refspec so a damaged/minimal remote.fetch config cannot leave it stale.
+    git fetch --quiet origin +refs/heads/main:refs/remotes/origin/main
+}
+
+snapshot_direct_s3_preflight() {
+    local tmp_dir
+    tmp_dir="$(mktemp -d)"
+    # Ensure tmp_dir is cleaned up on any return path or interrupt.
+    trap 'rm -rf "$tmp_dir"' RETURN
+    local direct_paths="$tmp_dir/direct-s3.paths"
+    local direct_notes="$tmp_dir/direct-s3-notes.paths"
+    local git_paths="$tmp_dir/git.paths"
+    local direct_not_git="$tmp_dir/direct-s3-not-git.paths"
+
+    if ! rclone lsf "$CLOUD_REMOTE" --recursive --files-only 2>/dev/null | LC_ALL=C sort > "$direct_paths"; then
+        echo "[wiki-snapshot] WARN: direct-S3 preflight could not list $CLOUD_REMOTE"
+        return 0
+    fi
+
+    grep -vE '^(\.skillwiki/|\.claude/|\.obsidian/|\.antigravitycli/|\.playwright-cli/|raw/\._\.DS_Store$|\._\.DS_Store$)' "$direct_paths" | LC_ALL=C sort -u > "$direct_notes" || true
+    (
+        cd "$SNAPSHOT_WORKTREE" || exit 1
+        fetch_origin_main_ref 2>/dev/null || true
+        if git rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+            git -c core.quotePath=false ls-tree -r --name-only origin/main
+        else
+            git -c core.quotePath=false ls-files
+        fi | LC_ALL=C sort -u
+    ) > "$git_paths" 2>/dev/null || {
+        echo "[wiki-snapshot] WARN: direct-S3 preflight could not list tracked files in snapshot worktree $SNAPSHOT_WORKTREE"
+        return 0
+    }
+
+    LC_ALL=C comm -23 "$direct_notes" "$git_paths" > "$direct_not_git"
+    SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT="$(wc -l < "$direct_not_git" | tr -d ' ')"
+    if [ "$SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT" != "0" ]; then
+        echo "[wiki-snapshot] WARN: direct-S3-not-git warning: $SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT note path(s) exist in direct S3 but not in $SNAPSHOT_WORKTREE"
+        sed -n '1,20p' "$direct_not_git" | sed 's/^/[wiki-snapshot] WARN: direct-S3-not-git: /'
+        return 2
+    fi
+
+    return 0
+}
+
+handle_direct_s3_preflight_before_sync() {
+    snapshot_direct_s3_preflight
+    local rc=$?
+    if [ "$rc" -eq 0 ]; then
+        return 0
+    fi
+
+    if [ "${WIKI_SNAPSHOT_ALLOW_S3_ONLY_NOTES:-0}" = "1" ]; then
+        log "WARNING: direct-S3 preflight found note paths missing from Git; WIKI_SNAPSHOT_ALLOW_S3_ONLY_NOTES=1 allows this live snapshot"
+        return 0
+    fi
+
+    case "$MAX_S3_ONLY_NOTES" in
+        ''|*[!0-9]*)
+            log "ERROR: invalid WIKI_SNAPSHOT_MAX_S3_ONLY_NOTES=$MAX_S3_ONLY_NOTES; refusing live snapshot"
+            return 1
+            ;;
+    esac
+
+    if [ "$SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT" -le "$MAX_S3_ONLY_NOTES" ]; then
+        log "WARNING: direct-S3 preflight found $SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT note path(s) missing from Git; within limit $MAX_S3_ONLY_NOTES, allowing live snapshot"
+        return 0
+    fi
+
+    log "ERROR: direct-S3-not-git count exceeds limit: $SNAPSHOT_DIRECT_S3_NOT_GIT_COUNT > $MAX_S3_ONLY_NOTES"
+    log "ERROR: Review and promote/delete the S3-only note paths first, raise WIKI_SNAPSHOT_MAX_S3_ONLY_NOTES, or set WIKI_SNAPSHOT_ALLOW_S3_ONLY_NOTES=1 for an explicitly approved promotion run"
+    return 1
+}
+
+# ── Guard: --max-delete verification ───────────────────────
+# Verify that this script (or a target script) has the --max-delete guard.
+# Returns 0 if guard is present, 1 if missing.
+wiki_snapshot_assert_guards() {
+    local script_path="${1:-$0}"
+
+    if [ ! -f "$script_path" ]; then
+        echo "FATAL: snapshot script not found: $script_path" >&2
+        return 1
+    fi
+
+    if grep -q -- '--max-delete' "$script_path" 2>/dev/null; then
+        return 0
+    else
+        echo "FATAL: --max-delete guard MISSING from $script_path" >&2
+        echo "Do NOT run this script on production until the guard is added." >&2
+        echo "Reference: raw/transcripts/2026-05-23-bug-sg01-snapshot-destructive-rclone-sync.md" >&2
+        return 1
+    fi
+}
+
+# Self-check: ensure THIS script contains its own --max-delete guard.
+if ! wiki_snapshot_assert_guards "$0"; then
+    echo "[wiki-snapshot] Self-guard check failed — refusing to run." >&2
+    exit 1
+fi
+
+# ── Dry-run mode ────────────────────────────────────────────
+DRY_RUN=false
+[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=true
+
+if [ "$DRY_RUN" = true ]; then
+    echo "[wiki-snapshot] DRY RUN"
+    echo "  WIKI_DIR          = $WIKI_DIR"
+    echo "  SNAPSHOT_WORKTREE = $SNAPSHOT_WORKTREE"
+    echo "  LOCK_FILE         = $LOCK_FILE"
+    echo "  LOG_FILE          = $LOG_FILE"
+    echo "  CLOUD_REMOTE      = $CLOUD_REMOTE"
+    echo "  REPAIR_SCRIPT     = $REPAIR_SCRIPT"
+    echo "[wiki-snapshot] DRY RUN: --max-delete guard verified (present in $0)"
+    snapshot_direct_s3_preflight || true
+    echo "[wiki-snapshot] DRY RUN: would acquire $LOCK_FILE, rclone sync, git commit, push."
+    echo "[wiki-snapshot] DRY RUN: Complete. No changes made."
+    exit 0
+fi
+
+mkdir -p "$(dirname "$LOG_FILE")"
+
+# ── Lock file to prevent concurrent execution ──────────────
+exec 200>"$LOCK_FILE"
+if ! flock -n 200; then
+    echo "$(date '+%Y-%m-%d %H:%M:%S') ERROR: Another instance of wiki-snapshot is running. Exiting."
+    exit 1
+fi
+
+# Logging helper
+log() {
+    echo "$(date '+%Y-%m-%d %H:%M:%S') $1" | tee -a "$LOG_FILE"
+}
+
+raw_dedup_guard() {
+    if [ "${WIKI_SNAPSHOT_RAW_DEDUP_GUARD:-1}" = "0" ]; then
+        log "raw_dedup guard skipped by WIKI_SNAPSHOT_RAW_DEDUP_GUARD=0"
+        return 0
+    fi
+
+    SKILLWIKI_BIN="${WIKI_SNAPSHOT_SKILLWIKI_BIN:-skillwiki}"
+    if ! command -v "$SKILLWIKI_BIN" >/dev/null 2>&1; then
+        log "ERROR: skillwiki CLI unavailable; refusing to commit snapshot without raw_dedup guard"
+        return 1
+    fi
+
+    GUARD_LOG="${RCLONE_LOG}.raw-dedup-guard"
+    if ! "$SKILLWIKI_BIN" lint "$SNAPSHOT_WORKTREE" --only raw_dedup --summary >"$GUARD_LOG" 2>&1; then
+        log "ERROR: raw_dedup guard failed after cloud sync; refusing to commit snapshot"
+        cat "$GUARD_LOG" >>"$LOG_FILE" 2>/dev/null || true
+        rm -f "$GUARD_LOG"
+        return 1
+    fi
+
+    rm -f "$GUARD_LOG"
+    log "raw_dedup guard passed"
+    return 0
+}
+
+conflict_marker_guard() {
+    if [ "${WIKI_SNAPSHOT_CONFLICT_MARKER_GUARD:-1}" = "0" ]; then
+        log "conflict-marker guard skipped by WIKI_SNAPSHOT_CONFLICT_MARKER_GUARD=0"
+        return 0
+    fi
+
+    local findings
+    findings="$(mktemp)" || { log "ERROR: could not create conflict-marker scan temp file"; return 1; }
+    if ! vault_sync_scan_conflict_markers "$SNAPSHOT_WORKTREE" "$findings"; then
+        log "ERROR: conflict marker blocks found after cloud sync; refusing to commit snapshot"
+        vault_sync_log_conflict_marker_findings "$findings" "$LOG_FILE"
+        rm -f "$findings"
+        return 1
+    fi
+    rm -f "$findings"
+    log "conflict-marker guard passed"
+    return 0
+}
+
+refresh_git_baseline() {
+    (
+        cd "$SNAPSHOT_WORKTREE" || exit 1
+        fetch_origin_main_ref 2>/dev/null || exit 2
+
+        if [ -n "$(git status --porcelain)" ]; then
+            exit 3
+        fi
+
+        if git merge-base --is-ancestor HEAD origin/main 2>/dev/null; then
+            if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]; then
+                git merge --ff-only origin/main >/dev/null
+                exit 4
+            fi
+            exit 0
+        fi
+
+        exit 5
+    )
+    local rc=$?
+    case "$rc" in
+        0) return 0 ;;
+        4) log "Git baseline fast-forwarded to origin/main before S3 sync"; return 0 ;;
+        2) log "WARNING: Could not fetch origin/main before S3 sync; continuing with existing refs"; return 0 ;;
+        3) log "WARNING: Snapshot worktree dirty before S3 sync; skipping baseline fast-forward"; return 0 ;;
+        5) log "WARNING: Snapshot worktree is not an ancestor of origin/main; repair step will handle it after S3 sync"; return 0 ;;
+        *) log "WARNING: Git baseline refresh failed rc=$rc; continuing"; return 0 ;;
+    esac
+}
+
+log "=== Wiki Snapshot: $DATE ==="
+
+# Check disk space (need at least 100MB free)
+AVAILABLE_KB=$(df -k "$SNAPSHOT_WORKTREE" | awk 'NR==2 {print $4}')
+if [ "$AVAILABLE_KB" -lt 102400 ]; then
+    log "ERROR: Insufficient disk space. Only ${AVAILABLE_KB}KB available, need 100MB."
+    exit 1
+fi
+
+# Check if git directory exists
+if [ ! -d "$SNAPSHOT_WORKTREE/.git" ]; then
+    log "ERROR: Git worktree not found or not a git repo: $SNAPSHOT_WORKTREE"
+    exit 1
+fi
+
+refresh_git_baseline
+
+# Single-authority root projections before FUSE/S3 pull promotion.
+if command -v skillwiki >/dev/null 2>&1; then
+    if ! skillwiki projections materialize "$WIKI_DIR" --write >>"$LOG_FILE" 2>&1; then
+        log "FAIL root projection materialization; snapshot promotion refused"
+        exit 1
+    fi
+    log "OK projections materialize before snapshot sync"
+fi
+
+# Common rclone options
+# NOTE: rclone sync already deletes by default; exclusions prevent .git deletion
+RCLONE_OPTS=(
+    --exclude ".snapshots/**"
+    --exclude ".git/**"
+    --exclude ".obsidian/**"
+    --exclude ".skillwiki/**"
+    --exclude ".claude/**"
+    --exclude ".antigravitycli/**"
+    --exclude ".playwright-cli/**"
+    --exclude "._*"
+    --exclude ".conflict*"
+    --exclude "*.conflict-*"
+    --checksum
+    --transfers 8
+    --checkers 16
+    --fast-list
+    --timeout 5m
+    --contimeout 1m
+    --max-delete 10
+)
+
+if ! handle_direct_s3_preflight_before_sync; then
+    exit 1
+fi
+
+# Sync from cloud directly to git dir using rclone
+echo "Syncing from cloud to git repo (via rclone)..."
+
+if ! rclone sync "$CLOUD_REMOTE" "$SNAPSHOT_WORKTREE" "${RCLONE_OPTS[@]}" --stats 10s 2>&1 | tee "$RCLONE_LOG"; then
+    RCLONE_EXIT=$?
+    log "ERROR: Rclone sync failed with exit code $RCLONE_EXIT"
+    log "Last 50 lines of output:"
+    tail -50 "$RCLONE_LOG" >> "$LOG_FILE" 2>/dev/null || true
+    rm -f "$RCLONE_LOG"
+    exit 1
+fi
+
+rm -f "$RCLONE_LOG"
+
+# Verify sync actually happened
+if [ ! -f "$SNAPSHOT_WORKTREE/index.md" ]; then
+    log "ERROR: Sync verification failed - index.md not found in git dir"
+    exit 1
+fi
+
+# --- Delete-intent no-resurrect ---
+# Git is SSOT for intentional absences. After S3→worktree sync, strip any path
+# that has an active tombstone on origin/main and optionally prune S3.
+snapshot_apply_delete_intents() {
+    if ! command -v delete_intent_list_active_paths_from_git >/dev/null 2>&1 \
+        && ! command -v delete_intent_list_active_paths >/dev/null 2>&1; then
+        log "WARNING: delete-intent helpers unavailable; skipping tombstone no-resurrect"
+        return 0
+    fi
+
+    # Re-materialize ledger from git so rclone sync cannot drop git-only intents,
+    # then list from the worktree (single parse — avoid re-git-show of every blob).
+    (
+        cd "$SNAPSHOT_WORKTREE" || exit 0
+        fetch_origin_main_ref 2>/dev/null || true
+        if git rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
+            git checkout origin/main -- meta/delete-intents/ 2>/dev/null || true
+        fi
+    )
+
+    local paths_file pruned=0
+    paths_file="$(mktemp)"
+    if command -v delete_intent_list_active_paths >/dev/null 2>&1; then
+        delete_intent_list_active_paths "$SNAPSHOT_WORKTREE" > "$paths_file" 2>/dev/null || true
+    elif command -v delete_intent_list_active_paths_from_git >/dev/null 2>&1; then
+        delete_intent_list_active_paths_from_git "$SNAPSHOT_WORKTREE" origin/main > "$paths_file" 2>/dev/null || true
+    fi
+
+    if [ ! -s "$paths_file" ]; then
+        rm -f "$paths_file"
+        log "delete-intent: no active tombstones"
+        return 0
+    fi
+
+    local rel_path
+    while IFS= read -r rel_path; do
+        [ -z "$rel_path" ] && continue
+        if [ -e "$SNAPSHOT_WORKTREE/$rel_path" ]; then
+            rm -f "$SNAPSHOT_WORKTREE/$rel_path"
+            log "delete-intent: stripped resurrected path from worktree: $rel_path"
+        fi
+        # Bounded S3 prune for tombstoned paths still present on remote.
+        if [ "$pruned" -lt 10 ]; then
+            if rclone deletefile "${CLOUD_REMOTE%/}/$rel_path" >>"$LOG_FILE" 2>&1; then
+                log "delete-intent: pruned S3 object $rel_path"
+                pruned=$((pruned + 1))
+            fi
+        fi
+    done < "$paths_file"
+
+    rm -f "$paths_file"
+    log "delete-intent: no-resurrect pass complete (s3_pruned=$pruned)"
+    return 0
+}
+
+snapshot_apply_delete_intents
+
+snapshot_direct_s3_preflight || true
+
+# Change to git dir for operations
+cd "$SNAPSHOT_WORKTREE" || { log "ERROR: Failed to cd to $SNAPSHOT_WORKTREE"; exit 1; }
+
+# Configure git if not already set
+git config user.email "snapshot@vault-sync.local" 2>/dev/null || true
+git config user.name "Vault Sync Snapshot" 2>/dev/null || true
+
+if command -v git_case_assert_clean >/dev/null 2>&1; then
+    if ! CASE_CONFLICTS=$(git_case_conflicts); then
+        log "ERROR: Case-only path collision detected; refusing to commit snapshot"
+        printf '%s\n' "$CASE_CONFLICTS" | tee -a "$LOG_FILE"
+        exit 1
+    fi
+else
+    log "ERROR: git-case helper unavailable; refusing to commit snapshot"
+    exit 1
+fi
+
+# Check if git is in broken state (rebase in progress, merge conflicts, diverged)
+needs_repair=false
+
+# Check for rebase/merge in progress
+if [ -d ".git/rebase-merge" ] || [ -d ".git/rebase-apply" ] || [ -f ".git/MERGE_HEAD" ]; then
+    log "WARNING: Git rebase/merge in progress - needs repair"
+    needs_repair=true
+fi
+
+# Check for unmerged files
+if git diff --name-only --diff-filter=U | grep -q . 2>/dev/null; then
+    log "WARNING: Merge conflicts detected - needs repair"
+    needs_repair=true
+fi
+
+# Check if we're in detached HEAD state
+if ! git symbolic-ref -q HEAD >/dev/null 2>&1; then
+    log "WARNING: Detached HEAD state - needs repair"
+    needs_repair=true
+fi
+
+# Check if we can fast-forward to origin
+DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $3}')
+DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
+
+if ! git merge-base --is-ancestor HEAD "origin/$DEFAULT_BRANCH" 2>/dev/null; then
+    # Local HEAD is not an ancestor of origin - diverged
+    log "WARNING: Diverged from origin/$DEFAULT_BRANCH - needs repair"
+    needs_repair=true
+fi
+
+# Repair if needed
+if [ "$needs_repair" = true ]; then
+    log "Running git repair..."
+    if ! bash "$REPAIR_SCRIPT" 2>&1 | tee -a "$LOG_FILE"; then
+        log "ERROR: Git repair failed"
+        exit 1
+    fi
+    cd "$SNAPSHOT_WORKTREE" || { log "ERROR: Failed to cd to $SNAPSHOT_WORKTREE after repair"; exit 1; }
+
+    # Re-run rclone sync after repair to ensure we have latest
+    if ! rclone sync "$CLOUD_REMOTE" "$SNAPSHOT_WORKTREE" "${RCLONE_OPTS[@]}" --stats 10s 2>&1 | tee "$RCLONE_LOG"; then
+        log "ERROR: Post-repair rclone sync failed"
+        tail -50 "$RCLONE_LOG" >> "$LOG_FILE" 2>/dev/null || true
+        rm -f "$RCLONE_LOG"
+        exit 1
+    fi
+    rm -f "$RCLONE_LOG"
+    snapshot_apply_delete_intents
+fi
+
+if ! raw_dedup_guard; then
+    exit 1
+fi
+
+if ! conflict_marker_guard; then
+    exit 1
+fi
+
+# Check for changes
+if [ -z "$(git status --porcelain)" ]; then
+    log "No changes to commit"
+    exit 0
+fi
+
+# Re-check immediately before staging because rclone/repair may have changed the
+# tree after the first guard.
+if command -v git_case_assert_clean >/dev/null 2>&1; then
+    if ! CASE_CONFLICTS=$(git_case_conflicts); then
+        log "ERROR: Case-only path collision detected before git add; refusing to commit snapshot"
+        printf '%s\n' "$CASE_CONFLICTS" | tee -a "$LOG_FILE"
+        exit 1
+    fi
+fi
+
+# Commit
+echo "Committing changes..."
+if ! git add -A; then
+    log "ERROR: git add failed"
+    exit 1
+fi
+
+if ! git commit -m "Snapshot $DATE"; then
+    log "ERROR: git commit failed"
+    exit 1
+fi
+
+# Pull with rebase to get any remote changes (with retry)
+echo "Pulling from origin..."
+PULL_RETRIES=3
+PULL_SUCCESS=false
+
+for i in $(seq 1 $PULL_RETRIES); do
+    if git pull --rebase origin "$DEFAULT_BRANCH" 2>&1 | tee -a "$LOG_FILE"; then
+        PULL_SUCCESS=true
+        break
+    fi
+    log "WARNING: Pull attempt $i failed, retrying..."
+    sleep 5
+done
+
+if [ "$PULL_SUCCESS" = false ]; then
+    log "ERROR: Pull failed after $PULL_RETRIES attempts - attempting repair"
+    if bash "$REPAIR_SCRIPT" 2>&1 | tee -a "$LOG_FILE"; then
+        # After repair, commit timestamp will be slightly different
+        DATE=$(date +%Y%m%d_%H%M%S)
+        cd "$SNAPSHOT_WORKTREE" || { log "ERROR: Failed to cd after repair"; exit 1; }
+
+        # Re-sync after repair
+        rclone sync "$CLOUD_REMOTE" "$SNAPSHOT_WORKTREE" "${RCLONE_OPTS[@]}" 2>&1 | tee -a "$LOG_FILE" || true
+        if ! raw_dedup_guard || ! conflict_marker_guard; then
+            exit 1
+        fi
+        git add -A || true
+        git commit -m "Snapshot $DATE (post-repair)" || true
+    else
+        log "ERROR: Repair failed after pull failure"
+        exit 1
+    fi
+fi
+
+# Push (with retry)
+echo "Pushing to origin..."
+PUSH_RETRIES=3
+PUSH_SUCCESS=false
+
+for i in $(seq 1 $PUSH_RETRIES); do
+    if git push origin "$DEFAULT_BRANCH" 2>&1 | tee -a "$LOG_FILE"; then
+        PUSH_SUCCESS=true
+        break
+    fi
+    log "WARNING: Push attempt $i failed, retrying..."
+    sleep 5
+done
+
+if [ "$PUSH_SUCCESS" = true ]; then
+    log "Push successful"
+    log "Status: complete"
+    exit 0
+else
+    log "ERROR: Push failed after $PUSH_RETRIES attempts"
+    # Run repair for next attempt
+    bash "$REPAIR_SCRIPT" 2>&1 | tee -a "$LOG_FILE" || true
+    exit 1
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.63",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup && rm -rf ./skills && cp -r ../skills ./skills",
+    "build": "tsup && node ./scripts/copy-build-assets.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.63",
+  "version": "0.10.0",
   "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.9.63",
+  "version": "0.10.0",
   "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/README.md

@@ -40,3 +40,16 @@ canonical skill, agent, or hook assets. Run
 
 The sibling `vault-sync` plugin ships six additional operational skills under
 `packages/vault-sync/skills/` and is packaged separately from this skill set.
+
+
+## Managed Vault Mutation Contract
+
+Before a managed vault mutation, invoke the managed SkillWiki command while the draft remains outside the authoritative target path. The command resolves fleet authority, refuses existing unmerged/review-required state, converges an authorized Git writer, freezes the base OID, and only then applies the write. Do not run `git pull --rebase --autostash` after placing the authoritative change in the live worktree. Do not edit root `index.md` or root `log.md` directly; projection and log commands own those compatibility files.
+
+- typed pages: `skillwiki page publish <draft> <vault> --target <path>` then the same command with `--write`
+- archive: `skillwiki archive <path> <vault>`
+- ad-hoc structural log: `skillwiki log-append <vault> --content '<entry>'` (Release A dual-write) or event materialization (Release B)
+- project/root index: `skillwiki project-index <slug> <vault> --apply` and `skillwiki index rebuild <vault> --write` only through managed commands
+- log projection: `skillwiki log materialize <vault> [--write]`
+- paired projections: `skillwiki projections materialize <vault> [--write]`
+

package/skills/package.json

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

package/skills/proj-work/SKILL.md

@@ -67,3 +67,6 @@ Rules:
 - Writing spec/plan files outside the work folder.
 - Marking `status: completed` without a `completed:` date.
 - Accepting tasks.md status labels without independent disk verification.
+## Managed writes
+
+Use managed SkillWiki commands (`skillwiki page publish`, `skillwiki archive`) rather than editing root index.md/log.md directly.

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

@@ -67,3 +67,6 @@ Rules:
 - Writing spec/plan files outside the work folder.
 - Marking `status: completed` without a `completed:` date.
 - Accepting tasks.md status labels without independent disk verification.
+## Managed writes
+
+Use managed SkillWiki commands (`skillwiki page publish`, `skillwiki archive`) rather than editing root index.md/log.md directly.

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

@@ -75,6 +75,19 @@ path, run publisher dry-run, then run the same command with `--write`.
 - Non-typed project work items and immutable raw sources keep their existing
   workflows.
 
+
+## Managed Vault Mutation Contract
+
+Before a managed vault mutation, invoke the managed SkillWiki command while the draft remains outside the authoritative target path. The command resolves fleet authority, refuses existing unmerged/review-required state, converges an authorized Git writer, freezes the base OID, and only then applies the write. Do not run `git pull --rebase --autostash` after placing the authoritative change in the live worktree. Do not edit root `index.md` or root `log.md` directly; projection and log commands own those compatibility files.
+
+- typed pages: `skillwiki page publish <draft> <vault> --target <path>` then the same command with `--write`
+- archive: `skillwiki archive <path> <vault>`
+- ad-hoc structural log: `skillwiki log-append <vault> --content '<entry>'` (Release A dual-write) or event materialization (Release B)
+- project/root index: `skillwiki project-index <slug> <vault> --apply` and `skillwiki index rebuild <vault> --write` only through managed commands
+- log projection: `skillwiki log materialize <vault> [--write]`
+- paired projections: `skillwiki projections materialize <vault> [--write]`
+
+
 ## CLI probe and failsafe (vault-mutating skills)
 
 Vault fleets that combine S3 + GitHub need an explicit delete-intent path. Prefer the skillwiki CLI; when it is missing, agents that still have **git/gh access to the private vault remote** use **FAILSAFE-GIT**.