Skip to main content

Housekeeping (vault-lint)

Once a week, a small checker reads the vault's signpost files and looks for things that quietly break a shared vault. It fixes what it is certain about. It reports the rest.

Where you see it​

Most weeks, nowhere. The checker stays quiet when nothing changed. When it fixes something or finds a new problem, the owner gets one email saying what.

What happens, step by step​

  1. Monday morning, a timer on the box starts the check.
  2. lint.py reads every signpost file. These are the index and guide files, like CLAUDE.md, README.md, INDEX.md, and each project's state.md and context.md.
  3. It compares what it finds to baseline.json, a list of known old problems. It reports only what is new.
  4. It auto-fixes only the cases it is certain about. Example: a link says Pricing.md but the file is pricing.md. It fixes the capital letter.
  5. After fixing, it runs the whole check again to make sure the fix helped. If not, it undoes the fix.
  6. If anything was fixed or newly found, it sends the email.

What powers it​

PartWhat it does
lint.pyReads the signpost files and runs the seven rules.
baseline.jsonThe list of known old problems, so the report stays short.
vault-lint.timerStarts the check every Monday morning.
vault-lint-check.pyRuns the check on the box and sends the email.
fix-skill-paths and dreamSkills a person uses for fixes that need judgment.

The seven rules​

  1. Capital letters. A link's capitals must match the real file name.
  2. Dead links. A link must point at a file that exists.
  3. Routines listed. Every routine must appear on its plain-words page.
  4. No machine-specific paths. Shared files must not name things that exist on only one machine, like a folder path on the laptop.
  5. Every tool says where it runs. Each tool folder needs a row naming which machine runs it.
  6. Memory index stays short. The memory index's lines and sections must stay under a set length.
  7. No hiding rules. A git ignore rule must not be able to hide real vault folders from one machine.

Why it works this way​

Each rule traces back to a real problem. Rule 4 comes straight from the core principle: the vault holds only what is true on every machine.

Rule 7 has the best story. The vault has a list of things git should ignore. One line on that list was too loose. It matched any folder with a certain name, anywhere. Two real client folders happened to have that name. They existed only on the laptop, and git silently never saved them. The laptop's own check said "Clean," because from where it sat, everything looked fine. The box saw links pointing at folders it did not have, and reported them as dead. The two machines disagreed, and the box was right. Now a rule catches any ignore line that could do that.

Auto-fix only when certain

Only two kinds of fix happen on their own: wrong capital letters, and a moved file with exactly one same-named match. Anything that needs a choice is proposed, and a person makes the call.

Deciding which machine runs a tool, or which of two conflicting memories is wrong, is a judgment call. A checker guessing would make things worse. So rules 3 through 7 report and wait.

Connected to​