Metadata-Version: 2.4
Name: vaultlint
Version: 0.1.0
Summary: Consistency and staleness linter for Markdown vaults used as AI agent memory (Obsidian, CLAUDE.md, memory banks, agent knowledge bases).
Author: Automato
License: MIT
Project-URL: Homepage, https://github.com/PLACEHOLDER/vaultlint
Project-URL: Repository, https://github.com/PLACEHOLDER/vaultlint
Keywords: agent,memory,markdown,vault,obsidian,claude,linter,consistency
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# vaultlint

Consistency and staleness linter for Markdown vaults used as **AI agent memory** — Obsidian vaults, `CLAUDE.md`/`AGENTS.md` setups, memory banks, agent knowledge bases.

Agents read these files and act on what they say. A duplicate "next action" marker, a broken cross-reference, or a status line that's quietly gone stale can make an agent act on the wrong thing — silently. `vaultlint` catches that class of bug before it does.

## Why this exists

Existing tools cover adjacent ground but not this gap:
- `stalebrain` and `AgentLinter` audit a single instruction file (`CLAUDE.md`/`AGENTS.md`) against the repo.
- Generic Obsidian checkers (broken-link plugins, vault inspectors) target human PKM use, not the action-marker/state-consistency issues that specifically break an *agent* reading the vault.

`vaultlint` targets multi-file vaults with a history of decisions (the Obsidian/JARVIS pattern), checking for the exact class of bug that made this project necessary in the first place — see [Proof it works](#proof-it-works) below.

## Install

```bash
pip install vaultlint
```

(Not yet published — see status note at the bottom of this README.)

## Usage

```bash
vaultlint /path/to/your/vault
```

```
vaultlint report — 75 files scanned, 40 findings

  BROKEN_LINK: 37
  DUPLICATE_ACTION_MARKER: 2
  STALE_STATUS_CANDIDATE: 1

[WARNING] BROKEN_LINK — 03 - Automato/Opportunities/OPP-002-Autonomous-Digital-Business-Scan.md:12
    reference to 'OPPORTUNITY_HUNTER.md' does not resolve to an existing file in the vault
...
```

Options:

```bash
vaultlint /path/to/vault --json                      # machine-readable output
vaultlint /path/to/vault --stale-threshold-days 14    # tune staleness window (default: 30)
vaultlint /path/to/vault --fail-on error              # exit 1 if any error-level finding exists (CI-friendly)
```

Or without installing, straight from a checkout:

```bash
python3 -m vaultlint /path/to/vault
```

## What it checks (v0.1 — 3 rules, zero dependencies, fully static)

1. **BROKEN_LINK** — a Markdown `[text](path.md)` link or a backtick `` `path.md` `` reference that doesn't resolve to a real file in the vault.
2. **DUPLICATE_ACTION_MARKER** — a single file contains more than one "next action" marker (e.g. `## Next Action` / `NEXT ACTION:`). An agent reading the file may act on the wrong one.
3. **STALE_STATUS_CANDIDATE** — a `Status: ...` line reads as in-progress/pending in a file that hasn't been touched in N days. This is a heuristic (file mtime + keyword match), not a certainty — always flagged as `info`, meant for human review, not auto-action.

No LLM calls. No writes to your vault — read-only, always.

## Proof it works

Run read-only against the real, actively-growing JARVIS Obsidian vault this tool was built inside of: **40 real findings across 75 files** as of the latest run (up from 18/59 a few hours earlier in this same project's history — the count grows naturally as the vault grows, which is itself evidence the tool stays useful over time, not a regression). The bulk are genuinely broken cross-references left behind after renames/reorganizations and short-name backtick references across subfolders (the documented v0.1 limitation below — some of these are true positives, some are the known false-positive class), plus 2 files that accumulated a duplicate `Next Action` marker — the exact failure mode that motivated this tool, since it happened for real, more than once, in this same project's history. Full raw output: [`dogfood-report.json`](./dogfood-report.json).

## What v0.1 deliberately does NOT do

- No LLM-based semantic staleness judgment — only mtime + keyword heuristics. Cheaper, faster, more predictable. A v2 semantic mode is a possible future addition, not a v0.1 promise.
- Doesn't resolve short/ambiguous filename references (e.g. a backtick reference to `` `SCOPE.md` `` when it lives in a subfolder) — known limitation, see dogfood report.
- No git integration — uses file mtime as a universal proxy, since not every vault is a git repo.
- No auto-fix. `vaultlint` only reports; it never edits your vault.

## License

MIT — see [LICENSE](./LICENSE).

## Status

v0.1.0, locally built and tested (7/7 unit tests, dogfood-verified against a real 59-file vault). **Not yet published to PyPI or GitHub** — this repository/package is staged for release, pending publication approval.
