Building an Auto-Committing Knowledge Vault (Inbox-Only, Zero Direct Edits)

My knowledge base used to be a shared directory everyone could write to directly. Files got edited in place, changes overlapped, and the commit history was a mess of partial updates with no clear rationale. Every few weeks something would conflict or go missing and I’d spend an hour reconstructing what happened.

The fix was conceptually simple but took a while to trust: stop letting anyone — including myself — write directly to the source files. Everything goes through an inbox. A watcher picks it up, patches the sources, and commits automatically. Here is how the system is built and why the constraint matters more than the automation.

The Problem With Direct Edits

When knowledge files are writable by everyone, you get three compounding problems.

The first is collision. If two contributors both edit the same file — even different sections — one of them will overwrite the other’s changes unless they coordinate carefully. In an async workflow with multiple agents and humans, coordination overhead grows fast.

The second is audit trail decay. A commit that says “update sources” tells you nothing. You can’t tell what changed, why it changed, or who approved it. Six months later the rationale is gone.

The third is the hardest to fix retroactively: there is no natural choke point for validation. If editing a file is a one-step action, you can’t insert a review step without adding friction that people will route around. The inbox forces a review-before-apply structure by making “apply without inbox” physically impossible for anyone following the process.

The Architecture

The vault has three layers.

inbox/         ← patches are dropped here as spec files
sources/       ← the canonical knowledge base (read-only for contributors)
.git/          ← auto-commit fires after each inbox item is processed

Contributors write spec files into inbox/. The spec file is structured: it names the target file, the anchor (a unique string in the target), the position relative to the anchor, and the content to insert. It looks something like this:

# inbox/2026-07-22-add-redis-key-format.md
target: sources/infrastructure.md
anchor: "## Queue Configuration"
position: after
content: |
  ### Key Format

  All queue keys use colon separators: `team:queue:N`.
  The llen diagnostic must use the exact key string — omit the colons
  and it silently hits a nonexistent key and returns 0.
rationale: "Documented after debugging colon-stripped key bug (2026-07-22)"

The inbox watcher — a shell script running as a daemon — polls inbox/ for new files. When one appears, it reads the spec, verifies the anchor is unique in the target, applies the patch, moves the processed spec to inbox/processed/, and runs git add -p followed by git commit -m "inbox: <spec filename>".

The Watcher Script

The watcher is intentionally minimal. It does not interpret the content — it applies exactly what the spec says.

#!/usr/bin/env bash
# inbox-watch.sh — polls inbox/ and applies spec files

INBOX_DIR="/mnt/c/LLMWiKi/inbox"
SOURCES_DIR="/mnt/c/LLMWiKi/sources"
PROCESSED_DIR="$INBOX_DIR/processed"

mkdir -p "$PROCESSED_DIR"

while true; do
  for spec in "$INBOX_DIR"/*.md; do
    [ -f "$spec" ] || continue

    target=$(grep '^target:' "$spec" | awk '{print $2}')
    anchor=$(grep '^anchor:' "$spec" | sed 's/anchor: *//' | tr -d '"')
    position=$(grep '^position:' "$spec" | awk '{print $2}')
    content_start=$(grep -n '^content:' "$spec" | head -1 | cut -d: -f1)

    # Extract content block (lines after 'content: |')
    content=$(tail -n +"$((content_start + 1))" "$spec" \
              | sed '/^rationale:/,$d' \
              | sed 's/^  //')

    full_target="$SOURCES_DIR/$target"

    # Verify anchor uniqueness
    count=$(grep -cF "$anchor" "$full_target" 2>/dev/null)
    if [ "$count" -ne 1 ]; then
      echo "SKIP $spec: anchor found $count times in $target"
      mv "$spec" "$PROCESSED_DIR/FAILED-$(basename "$spec")"
      continue
    fi

    # Apply patch
    python3 /usr/local/bin/apply-anchor-patch.py \
      --file "$full_target" \
      --anchor "$anchor" \
      --position "$position" \
      --content "$content"

    git -C "$SOURCES_DIR/.." add "$full_target"
    git -C "$SOURCES_DIR/.." commit -m "inbox: $(basename "$spec")"

    mv "$spec" "$PROCESSED_DIR/$(basename "$spec")"
    echo "Applied: $(basename "$spec")"
  done

  sleep 5
done

The Python helper handles the actual text insertion — find the anchor line, insert before or after it, write the file. The bash script owns the loop, the validation, and the commit.

Why the Inbox Rule Has to Be Absolute

The temptation to bypass the inbox for “small” or “obvious” changes is constant. Every time I’ve given in to it, something went wrong.

A direct edit skips anchor uniqueness verification. You search manually, think you found the right place, insert, and move on. Two months later someone else searches for the same anchor, finds two matches, and the second insertion lands in the wrong place.

A direct edit skips the commit message pattern. Commits become heterogeneous again — some with inbox: prefixes, some with freehand messages. Searching the history for all changes to a given source file now requires reading every commit manually instead of grepping for inbox:.

Most importantly, a direct edit breaks the trust model. If contributors know the inbox is sometimes bypassed, they start assuming their inbox submissions might be preempted by direct edits. They start double-checking whether their spec was applied or whether someone edited around it. The audit trail stops being trustworthy.

The rule is: if you want to change a source file, write a spec. No exceptions.

What the Commit History Looks Like

After three months running this system, the commit log for the knowledge vault is clean enough to be actually useful:

inbox: 2026-07-22-add-redis-key-format.md
inbox: 2026-07-20-update-team-routing-table.md
inbox: 2026-07-19-document-mnt-c-acl-workaround.md
inbox: 2026-07-18-add-daemon-startup-check.md
inbox: 2026-07-16-correct-pane-index-reference.md

Every commit corresponds to a spec file in inbox/processed/. To understand what changed and why, you open the spec. The rationale field is required in the spec format, so there is always an answer to “why did this change?”

Grepping the history for changes to a specific source file is now a two-step operation: git log --oneline -- sources/infrastructure.md gives you a list of commit hashes, and git show <hash>:inbox/processed/<spec>.md gives you the rationale for each.

Handling Conflicts in the Inbox

Occasionally two specs target the same anchor or the same region of the same file. When this happens, the watcher applies the first one, commits, and then re-evaluates the second against the now-modified file. Sometimes the second spec’s anchor is still unique and the patch applies cleanly. Sometimes the anchor was modified by the first patch and the second spec fails uniqueness verification.

Failed specs go to inbox/processed/FAILED-<name>.md with a note. A separate review step catches failures and either rewrites the spec against the updated anchor or drops it if the content was already incorporated.

This is one reason the inbox exists: conflicts surface as failed specs, not as corrupted source files. The source files are never in an invalid state because nothing touches them without a verified anchor match.

When to Use This Pattern

The inbox-watcher-commit pattern is worth the setup cost when:

• Multiple contributors write to the same knowledge base
• You need an audit trail with rationale, not just a diff
• Changes need to be reviewed or approved before they land in source
• You want git history to be searchable by intent rather than by author

It is overkill for a personal notes directory that one person edits directly. The overhead is in the spec-writing and the tooling, not the watcher itself — the watcher is cheap once built. If you are spending more time resolving edit conflicts or hunting through git history than the spec-writing would cost, the system pays for itself quickly.

The key constraint is the no-direct-edit rule. The automation is useful. The constraint is what makes the system trustworthy.

---

The anchor-based patching technique the inbox relies on is described in more detail in the Automation section under anchor-based doc patching across many files. The queue daemon approach used by the watcher process is covered in the Tools & Reviews section.