haacked/dotfiles/vault

Vault Operations

The knowledge loop over the PostHog work vault at ~/dev/haacked/notes/PostHog (paths below are relative to ~/dev/haacked/notes). The schema (raw vs wiki vs working docs, the log rules) lives in PostHog/CLAUDE.md — read it before any operation. The operations log PostHog/log.md is both history and the ingest ledger: a backtick-wrapped vault-relative path anywhere in the log marks that raw source as ingested, so only ingest entries may backtick-wrap paths — every other entry type writes paths plain or as [[wikilinks]]. Ledger entries dated before 2026-08-18 name raw paths without the raw/ prefix (pre-move layout); both forms mark a source ingested.

Modes

Parse the first argument from user input.

Ingest mode

One source at a time — stay bounded, stay involved.

1. Resolve the target: an explicit vault-relative path or URL from the argument, else run the helper to pick the oldest unprocessed raw source:

scripts/vault-next-source.sh

It prints the oldest raw file not yet named by an ingest | log entry (stderr shows the remaining backlog count). --tranche N mode: call with N to get the N oldest and process each one fully, with its own log entry, before starting the next.

1. Read the source, then PostHog/Home.md, then only the wiki pages the source plausibly touches — index-first navigation, never a bulk scan.
2. Rewrite or create the affected wiki pages, bounded to ~10-15 pages per source. Distill, don't transcribe: capture decisions, facts, and system knowledge, not meeting play-by-play. Add [[wikilinks]] in both directions. Update Home.md only if a new area appeared. Never modify the raw source.
3. Append the ledger entry to PostHog/log.md — it MUST contain the source's backtick-wrapped vault-relative path, extension included (that exact token, inside an ingest | entry, is what marks the source processed):

## [YYYY-MM-DD] ingest | <short title>
 
Source: `raw/2026/07/Feature Flags - Growth Review.md`. Updated: [[page-one]], [[page-two]]. New: [[page-three]].

1. Report: source, pages updated/created, anything deliberately skipped.

Sources with nothing durable in them (a standup that's all PR links already tracked elsewhere, a meeting with no decisions) still get their log entry — Updated: none — no durable knowledge — so the backlog shrinks honestly.

Lint mode

Mechanical first, judgment second; scope judgment to [area] (a folder like repositories/posthog or reference) or pick a rotating slice — never the whole vault in one pass.

1. Mechanical checks:

(cd ~/dev/haacked/notes && markdownlint-cli2 "PostHog/**/*.md")
scripts/vault-lint-links.sh

The links helper reports dead [[wikilinks]], orphan wiki pages (no inbound links), and duplicate wiki page names (consolidation candidates — route to /vault consolidate, not lint fixes). Also check for loose files in vault roots and empty directories (convention violations per the schema).

1. Judgment checks over the scoped area only: contradictions between wiki pages, stale claims (dated assertions that no longer hold), missing cross-links between obviously related pages, duplicate or overlapping pages (same topic under different names — route to /vault consolidate).
2. Fix mechanical issues after a y/n confirmation — except dead links sourced from raw files, which are permanent (raw is never edited; consolidated-away targets are the common case): report, don't fix. Report judgment issues as a checklist; offer to capture deferred ones as /followup items.
3. Append a lint | entry to PostHog/log.md summarizing what was checked and fixed.

The daily ingest drip (bin/vault-ingest-run) already runs the links helper with --skip-raw-sources and files a lint | entry when a wiki page's link breaks, staying silent while the findings match the last report. Orphans, duplicates, markdownlint, and every judgment check belong to this mode.

Consolidate mode

Merge duplicate or overlapping wiki pages — one survivor absorbs the rest. Wiki layer only: never raw sources, plans/, archive/, or structural files (Home.md, log.md, CLAUDE.md, Followups.md). Interactive only — per-merge confirmation is the point; never run unattended.

1. Gather candidates: explicit pages in the argument form one cluster (a single page means: find and merge that page's duplicates); otherwise run the links helper (above) and take its "Duplicate wiki page names" clusters. When [area] is given, keep the clusters that touch it (clusters span directories by nature — never drop a cluster's out-of-area members) and add overlaps noticed while reading the area via Home.md. Cap a run at ~5 merges — stay bounded, stay involved.
2. Read every page in a cluster fully. Same name but genuinely different topics is a rename, not a merge — offer to rename the less canonical page and update its inbound links instead.
3. Pick the survivor: most inbound links, then the name that fits conventions (kebab-case in repositories/, Title Case elsewhere), then the most complete content.
4. Propose the merge and wait for y/n before writing anything: survivor, pages to absorb, count of inbound links to rewrite, and any links from raw sources that will keep pointing at the old name.
5. On yes: rewrite the survivor as one distilled page — every durable fact from all pages, union of outbound [[wikilinks]] minus links between the merged pages (they'd become self-links), no concatenated sections. Rewrite each inbound link to the survivor — grep for the old basename inside [[ ]] to catch [[name]], [[name|alias]], [[name#heading]], and [[dir/name]] forms; preserve aliases, and re-anchor or drop #heading fragments that don't exist on the survivor. Update links in every editable file — wiki pages, Home.md, Followups.md, and working docs under plans/ or archive/ — but never log.md or raw sources. Re-grep the old basename before deleting: remaining [[ ]] hits must be only raw sources, log.md, or quoted examples inside code fences. Then delete the absorbed pages with rm — the notes auto-backup agent owns git; never commit or push.
6. Append one consolidate | entry to PostHog/log.md for the run — survivor as a [[wikilink]], absorbed pages as plain paths, renames from step 2 logged the same way (old path → [[new-name]]). Never backtick-wrap a path here — per the ledger rule above, that would mark a raw source ingested:

## [YYYY-MM-DD] consolidate | <short title>
 
Merged reference/Feature Flags.md into [[feature-flags]]; rewrote 6 inbound links. Scope: reference.

1. Report: merges done, merges skipped and why, any raw-source links left pointing at deleted names.

Status mode

Report, using one Bash call where possible:

• Ingest backlog: scripts/vault-next-source.sh all | grep -c .
• Recent activity: the latest few ## [date] entries in PostHog/log.md
• Open follow-ups: ~/.dotfiles/ai/skills/followup/scripts/followup-open.sh 2>/dev/null | grep -c . (reports 0 when the followup skill isn't installed)
• Last lint: most recent lint | entry in PostHog/log.md (or "never")

Boundary: /vault vs /note vs /followup