Vault Presync

vault-presync

Pre-sync helper that handles the full sync pipeline for the ~/wiki vault: lint gate, untracked-file collision removal, conflict detection, and rebase-based merge.

When to use

• Before git push from the ~/wiki vault (after editing sessions)
• When git pull fails with "The following untracked working tree files would be overwritten by merge"
• When git merge --ff-only fails due to divergent histories (local + remote both have commits)
• After a Claude Code session that modified vault files
• Periodically to keep the local vault in sync with sg01 30-minute snapshots

What it does

1. Fetches remote state, reports AHEAD/BEHIND/DIRTY counts
2. Lint-delta gate — runs skillwiki sync lint-delta --base-ref origin/main; blocks only when new_errors > 0 (unless --force). Inherited debt is visible but non-blocking. Malformed/missing delta evidence fails closed.
3. Finds collisions — untracked local files that origin/main already tracks
4. Removes collisions — deletes byte-identical local copies (safe dedup); preserves local edits that differ
5. Detects rebase conflicts — when local and remote both touch the same files, warns before rebase
6. Canonical pull — delegates to wiki-pull-with-auto-resolve.sh (shared with unattended fetch). That helper owns an operation journal, freezes the remote tip as an exact OID, classifies rebase state, drops only fully materialized local commits, and auto-resolves archive/log conflicts.
7. Owned stash protection — dirty tracked/untracked files are stashed with a helper-owned message vault-sync op=<op_id> … and recorded by exact stash OID in the journal (not legacy peer-name stash guessing). Apply/drop use that OID only.
8. Reports remaining untracked files (genuine new work)

Execution

From terminal (CLI)

# After vault-sync-install, the helper is installed as a terminal command.
~/bin/wiki-sync.sh              # dry-run
~/bin/wiki-sync.sh --execute    # dedup + rebase
~/bin/wiki-sync.sh --force      # skip lint gate

vault-sync-install deploys the stable helper to the platform vault-sync bin directory and creates/repairs ~/bin/wiki-sync.sh when it is safe to do so. It will not clobber a real non-symlink user file at that path.

For repo/plugin development before install, run the skill-local helper directly:

bash packages/vault-sync/skills/vault-presync/wiki-sync.sh

Codex plugin install only installs plugin assets; it does not mutate host state, ~/bin, launchd, or systemd. Run vault-sync-install to install or repair the terminal helper on a host.

From Claude Code session

Invoke via the Skill tool — Claude runs the script inline:

/vault-presync --execute

Or run directly via Bash within a Claude session:

bash packages/vault-sync/skills/vault-presync/wiki-sync.sh --execute

The script auto-detects the vault root from skillwiki path → git root → script-relative path → $HOME/wiki fallback. No hardcoded paths.

Operation journal + frozen tip + one owned retry

wiki-pull-with-auto-resolve.sh records every convergence attempt under the vault git path (helper-owned journal files + recovery refs). Logs include op=<op_id> lines (for example STASH oid=… op=…, RETRY … op=…, OK pull completed op=…). There is no legacy wiki-pull auto-stash path.

Convergence properties:

Journal lifecycle (high level): begin → inventory → optional stash → rebasing → (optional retrying) → complete or review-required handoff.

Stale handoff cleanup (skillwiki ≥0.10.1): If many phase=review-required journals remain while the worktree is clean and Git is idle, managed writes fail closed. Run skillwiki doctor, then skillwiki sync journal list and skillwiki sync journal clear-stale --dry-run (then without --dry-run when safe). Managed preflight auto-supersedes when target_oid is already an ancestor of HEAD and no sequencer/unmerged paths remain, even when unrelated WIP keeps the worktree dirty. If the former pull owner also left a dead managed-write lock, the same acquire preserves/reclaims that lock and continues. Live owners, active Git operations, unmerged paths, and unresolved/non-ancestor handoffs remain blocking.

After install/rollout, confirm pull logs show op= journal lines and no legacy auto-stash wording before touching $(platform_share_dir)/live-verify.ok (see vault-sync-install attended checklist).

Rebase-state classification (canonical pull helper)

Before pull, wiki-pull-with-auto-resolve.sh classifies leftover sequencer state:

Never raw-rm sequencer directories or git rebase --abort for unattended cleanup: abort resets the tip to orig-head and can discard newer authored work (2026-07-11 incident class).

Materialized-commit proof

Local commits fully present on the remote tip may be dropped from the rebase todo only when every changed path is proven:

• Ordinary add/modify: target blob equals commit blob
• Delete: path absent on target
• log.md / */log.md: every added ## section body occurs byte-for-byte in the target log

Any partial match, rename, binary mismatch, raw-path difference, or unprovable change retains the commit or stops for review — never silent drop.

Lint-delta fail-closed

Publication and presync execute parse skillwiki sync lint-delta JSON:

• Report full_errors / base_errors / new_errors / resolved_errors
• Block only when new_errors > 0
• If the CLI is missing or JSON is malformed → fail closed (do not skip lint)

Rebase conflict resolution

When both local and remote touch the same files, git rebase pauses with conflicts. The script detects this pre-rebase (step 5) and warns which files overlap. If conflicts occur during rebase:

1. Find conflicted files: git diff --name-only --diff-filter=U
2. Frontmatter updated: conflicts — always keep the newer timestamp
3. Body conflicts — prefer the version with more content (the other side may be a truncated rclone race victim)
4. Mark resolved: git add <file>
5. Continue: git rebase --continue
6. Restore owned stash: only the journaled stash OID is applied/dropped (if the pull helper stashed before rebase)

To abort a broken rebase when you intend to discard the in-progress replay: git rebase --abort (attended only — unattended cleanup never uses abort for stale-clean state).

Lint gate

The script runs skillwiki sync lint-delta before syncing. Only new errors block the sync (use --force to override). Inherited full-error debt is warned but non-blocking. Malformed delta evidence fails closed. This prevents pushing malformed frontmatter (like the 2026-05-22 YAML bug where orphaned - tags lines broke 8 pages).

Conflict-marker guard

If sync reports conflict_markers, inspect the reported file and remove the literal Git marker block after preserving the intended content. Then run:

skillwiki lint --only conflict_markers
~/bin/wiki-sync.sh --execute

Multi-writer sync topology (current, 2026-05-22)

The ~/wiki vault has three concurrent writers:

Key insight: Both sg01 and macOS Claude Code can commit and push to GitHub independently. This creates divergent histories — macOS may have 1-3 local commits while sg01 pushes 15+ snapshot commits. The script uses git pull --rebase (not git merge --ff-only) to replay local commits on top of remote, which handles this naturally.

Collision pattern: sg01 pushes files to GitHub that also exist as untracked locally (from rclone bisync, drift-apply, or concurrent Claude sessions). The script removes byte-identical duplicates and preserves files with local edits.

2026-05-22 incident note: A rclone VFS write-back race on sg01 truncated 30+ wiki pages. The presync lint gate would have caught the resulting malformed YAML (orphaned list items below tags: lines) before they reached GitHub. The skillwiki CLI v0.5.4 safeWritePage guard now prevents recurrence at the write layer.

After wiki-sync

Once complete, the vault is ready for:

• git push (local commits replay cleanly on top of remote)
• git pull (no collision errors)
• New Claude Code sessions (working tree is consistent with remote)
• skillwiki lint (errors caught before push, not after)