vaultlint 0.1.0__tar.gz

vaultlint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vaultlint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vaultlint-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+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.

vaultlint-0.1.0/README.md

@@ -0,0 +1,80 @@
+# 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.

vaultlint-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vaultlint"
+version = "0.1.0"
+description = "Consistency and staleness linter for Markdown vaults used as AI agent memory (Obsidian, CLAUDE.md, memory banks, agent knowledge bases)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "Automato" }
+]
+keywords = ["agent", "memory", "markdown", "vault", "obsidian", "claude", "linter", "consistency"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = []
+
+[project.scripts]
+vaultlint = "vaultlint.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/PLACEHOLDER/vaultlint"
+Repository = "https://github.com/PLACEHOLDER/vaultlint"
+
+[tool.setuptools]
+packages = ["vaultlint"]

vaultlint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vaultlint-0.1.0/tests/test_linter.py

@@ -0,0 +1,64 @@
+"""Plain-assert test suite for vaultlint (no external test framework — zero dependencies).
+Run with: python3 tests/test_linter.py
+"""
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from vaultlint import lint_vault  # noqa: E402
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+
+
+def _findings_for(result, filename, rule=None):
+    out = [f for f in result["findings"] if f["file"].endswith(filename)]
+    if rule:
+        out = [f for f in out if f["rule"] == rule]
+    return out
+
+
+def run():
+    failures = []
+
+    # make STALE_STATUS.md look 60 days old so the staleness rule can fire
+    stale_path = FIXTURES / "bad" / "STALE_STATUS.md"
+    sixty_days_ago = time.time() - 60 * 86400
+    os.utime(stale_path, (sixty_days_ago, sixty_days_ago))
+
+    result = lint_vault(str(FIXTURES), stale_threshold_days=30)
+
+    checks = [
+        ("clean file has zero findings",
+         len(_findings_for(result, "good/CLEAN_STATE.md")) == 0),
+        ("second clean file has zero findings",
+         len(_findings_for(result, "good/ANOTHER_GOOD_FILE.md")) == 0),
+        ("duplicate Next Action is caught",
+         len(_findings_for(result, "DUPLICATE_ACTION.md", "DUPLICATE_ACTION_MARKER")) >= 1),
+        ("broken markdown link is caught",
+         any("missing/plan.md" in f["message"] for f in _findings_for(result, "BROKEN_LINK.md", "BROKEN_LINK"))),
+        ("broken backtick reference is caught",
+         any("DOES_NOT_EXIST.md" in f["message"] for f in _findings_for(result, "BROKEN_LINK.md", "BROKEN_LINK"))),
+        ("stale in-progress status (60 days old) is caught",
+         len(_findings_for(result, "STALE_STATUS.md", "STALE_STATUS_CANDIDATE")) >= 1),
+        ("no false positive on terminal status in clean fixtures",
+         len(_findings_for(result, "good/", "STALE_STATUS_CANDIDATE")) == 0),
+    ]
+
+    for name, ok in checks:
+        status = "PASS" if ok else "FAIL"
+        print(f"[{status}] {name}")
+        if not ok:
+            failures.append(name)
+
+    print()
+    print(f"{len(checks) - len(failures)}/{len(checks)} checks passed")
+    if failures:
+        print("FAILED:", failures)
+        sys.exit(1)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    run()

vaultlint-0.1.0/vaultlint/__init__.py

@@ -0,0 +1,3 @@
+from .linter import lint_vault, format_report
+
+__all__ = ["lint_vault", "format_report"]

vaultlint-0.1.0/vaultlint/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

vaultlint-0.1.0/vaultlint/cli.py

@@ -0,0 +1,47 @@
+"""Command-line entry point for vaultlint."""
+import argparse
+import json
+import sys
+
+from .linter import lint_vault, format_report
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="vaultlint",
+        description="Scan a Markdown vault (agent memory / knowledge base) for staleness and consistency issues.",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="vault root directory (default: current directory)")
+    parser.add_argument(
+        "--stale-threshold-days",
+        type=int,
+        default=30,
+        help="days without modification before an in-progress status is flagged as stale (default: 30)",
+    )
+    parser.add_argument("--json", action="store_true", help="print machine-readable JSON instead of the text report")
+    parser.add_argument(
+        "--fail-on",
+        choices=["error", "warning", "info", "never"],
+        default="never",
+        help="exit with status 1 if any finding at or above this severity exists (default: never)",
+    )
+    args = parser.parse_args(argv)
+
+    result = lint_vault(args.path, stale_threshold_days=args.stale_threshold_days)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(format_report(result))
+
+    if args.fail_on == "never":
+        return 0
+    severity_rank = {"info": 0, "warning": 1, "error": 2}
+    threshold = severity_rank[args.fail_on]
+    if any(severity_rank.get(f["severity"], 0) >= threshold for f in result["findings"]):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vaultlint-0.1.0/vaultlint/linter.py

@@ -0,0 +1,82 @@
+"""vaultlint core: scans a directory of Markdown files (an AI agent's memory/vault)
+for staleness and consistency issues that could make an agent act on outdated state.
+"""
+import json
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from .rules import rule_broken_links, rule_duplicate_action_marker, rule_stale_status
+
+DEFAULT_ACTION_MARKERS = [
+    ("Next Action heading", r"##\s*Next Action"),
+    ("NEXT ACTION label", r"NEXT ACTION\s*:"),
+]
+
+DEFAULT_IGNORE_DIRS = {".obsidian", ".git", "node_modules", "__pycache__"}
+
+
+def _collect_md_files(vault_root: Path, ignore_dirs: set):
+    files = []
+    for p in vault_root.rglob("*.md"):
+        if any(part in ignore_dirs for part in p.relative_to(vault_root).parts):
+            continue
+        files.append(p)
+    return files
+
+
+def lint_vault(vault_root: str, stale_threshold_days: int = 30, ignore_dirs: set = None) -> dict:
+    vault_root = Path(vault_root).resolve()
+    ignore_dirs = ignore_dirs or DEFAULT_IGNORE_DIRS
+    md_files = _collect_md_files(vault_root, ignore_dirs)
+    rel_paths = {str(p.relative_to(vault_root)) for p in md_files}
+
+    now = time.time()
+    findings = []
+    for path in md_files:
+        rel = str(path.relative_to(vault_root))
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        mtime_days = (now - path.stat().st_mtime) / 86400.0
+
+        findings += rule_broken_links(rel, text, vault_root, rel_paths)
+        findings += rule_duplicate_action_marker(rel, text, DEFAULT_ACTION_MARKERS)
+        findings += rule_stale_status(rel, text, mtime_days, stale_threshold_days)
+
+    by_rule = {}
+    for f in findings:
+        by_rule.setdefault(f.rule, 0)
+        by_rule[f.rule] += 1
+
+    return {
+        "vault_root": str(vault_root),
+        "files_scanned": len(md_files),
+        "findings_count": len(findings),
+        "findings_by_rule": by_rule,
+        "findings": [asdict(f) for f in findings],
+    }
+
+
+def format_report(result: dict) -> str:
+    lines = [
+        f"vaultlint report — {result['files_scanned']} files scanned, {result['findings_count']} findings",
+        "",
+    ]
+    for rule, count in sorted(result["findings_by_rule"].items()):
+        lines.append(f"  {rule}: {count}")
+    lines.append("")
+    for f in result["findings"]:
+        lines.append(f"[{f['severity'].upper()}] {f['rule']} — {f['file']}:{f['line']}")
+        lines.append(f"    {f['message']}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    import sys
+    root = sys.argv[1] if len(sys.argv) > 1 else "."
+    result = lint_vault(root)
+    print(format_report(result))
+    print()
+    print(json.dumps(result, indent=2)[:0])  # keep import used; full json written by caller

vaultlint-0.1.0/vaultlint/rules.py

@@ -0,0 +1,101 @@
+"""Detection rules for vaultlint. Each rule is pure: (path, text, ctx) -> list[Finding]."""
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+MD_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)\s]+)\)")
+BACKTICK_PATH_RE = re.compile(r"`([\w0-9 \-\/\.]+\.md)`")
+
+IN_PROGRESS_KEYWORDS = [
+    "next", "planned", "not started", "em andamento", "todo", "pending",
+    "waiting", "in progress", "ready to start", "backlog",
+]
+TERMINAL_KEYWORDS = [
+    "done", "completed", "concluído", "concluido", "reject", "kill",
+    "pass", "current", "histórico", "historico", "congelado", "accepted",
+    "rejected", "archived", "frozen", "revise",
+]
+
+
+@dataclass
+class Finding:
+    rule: str
+    file: str
+    line: int
+    message: str
+    severity: str = "warning"
+
+
+def rule_broken_links(rel_path: str, text: str, vault_root: Path, all_files: set) -> list:
+    findings = []
+    lines = text.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        candidates = []
+        for m in MD_LINK_RE.finditer(line):
+            target = m.group(2)
+            if target.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            candidates.append(target)
+        for m in BACKTICK_PATH_RE.finditer(line):
+            candidates.append(m.group(1))
+        for target in candidates:
+            target_clean = target.split("#")[0].strip()
+            if not target_clean:
+                continue
+            if target_clean in all_files:
+                continue
+            # also try resolved relative to the referencing file's directory
+            file_dir_rel = str(Path(rel_path).parent / target_clean)
+            if file_dir_rel in all_files:
+                continue
+            findings.append(Finding(
+                rule="BROKEN_LINK",
+                file=rel_path,
+                line=lineno,
+                message=f"reference to '{target_clean}' does not resolve to an existing file in the vault",
+            ))
+    return findings
+
+
+def rule_duplicate_action_marker(rel_path: str, text: str, marker_patterns: list) -> list:
+    findings = []
+    lines = text.splitlines()
+    for pattern_name, pattern in marker_patterns:
+        hits = [i + 1 for i, line in enumerate(lines) if re.match(pattern, line.strip(), re.IGNORECASE)]
+        if len(hits) > 1:
+            findings.append(Finding(
+                rule="DUPLICATE_ACTION_MARKER",
+                file=rel_path,
+                line=hits[0],
+                message=f"marker '{pattern_name}' appears {len(hits)} times (lines {hits}) — a file should have exactly one, or the agent may act on the wrong one",
+                severity="error",
+            ))
+    return findings
+
+
+STATUS_LINE_RE = re.compile(r"(?:\*\*)?status(?:\*\*)?\s*[:\-]\s*(.+)", re.IGNORECASE)
+
+
+def rule_stale_status(rel_path: str, text: str, mtime_days: float, stale_threshold_days: int) -> list:
+    findings = []
+    lines = text.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        m = STATUS_LINE_RE.search(line)
+        if not m:
+            continue
+        value = m.group(1).lower()
+        is_in_progress = any(k in value for k in IN_PROGRESS_KEYWORDS)
+        is_terminal = any(k in value for k in TERMINAL_KEYWORDS)
+        if is_in_progress and not is_terminal and mtime_days > stale_threshold_days:
+            findings.append(Finding(
+                rule="STALE_STATUS_CANDIDATE",
+                file=rel_path,
+                line=lineno,
+                message=(
+                    f"status line looks in-progress/pending ('{m.group(1).strip()[:60]}') "
+                    f"but file has not been modified in {mtime_days:.0f} days (threshold {stale_threshold_days}) "
+                    f"— HEURISTIC, may be a deliberately preserved historical snapshot, needs human review"
+                ),
+                severity="info",
+            ))
+    return findings

vaultlint-0.1.0/vaultlint.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+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.

vaultlint-0.1.0/vaultlint.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_linter.py
+vaultlint/__init__.py
+vaultlint/__main__.py
+vaultlint/cli.py
+vaultlint/linter.py
+vaultlint/rules.py
+vaultlint.egg-info/PKG-INFO
+vaultlint.egg-info/SOURCES.txt
+vaultlint.egg-info/dependency_links.txt
+vaultlint.egg-info/entry_points.txt
+vaultlint.egg-info/top_level.txt

vaultlint-0.1.0/vaultlint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vaultlint-0.1.0/vaultlint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vaultlint = vaultlint.cli:main

vaultlint-0.1.0/vaultlint.egg-info/top_level.txt

@@ -0,0 +1 @@
+vaultlint