Skip to content

v0.1.0 — prove which docs are stale

Latest
Latest

Choose a tag to compare

View all tags
@patkusch patkusch released this 01 Sep 18:24
· 16 commits to main since this release
v0.1.0
f9e25a3

Your markdown has no lifecycle. That's the bug.

kontext gives context documents one — so you can prove which docs are stale, pack fresh context for agents, and hand off state between sessions.

A document declares describes: globs. That turns an unfalsifiable assertion into a claim about code, and git already knows whether that code moved after the document last did. Two git log calls and a comparison. No LLM in the staleness path, so the verdict is deterministic and CI can gate on it.

Install

Note: the npm package (@patkusch/kontext) is not published yet. Install from source until it is.

git clone https://github.com/patkusch/kontext.git && cd kontext && npm install && npm run build && npm link

Then, in any repo:

kontext doctor

Zero setup, zero frontmatter required. It'll tell you how bad things actually are.

What's in 0.1.0

  • Staleness proven from git, not guessed — six verdicts (fresh, drifting, stale, expired, orphaned, superseded), plus unverified for the honest middle. Every verdict cites a commit, a date, a glob, or a file count; a bare "stale" with no receipt is treated as a bug.
  • CLI — check, map, pack, init, handoff, doctor. pack assembles a context bundle under a token budget, freshest first. handoff writes session state so the next session starts where the last one stopped.
  • MCP server (kontext-mcp) with 7 freshness-aware tools, so an agent can ask what's current instead of slurping the whole repo into its context window.
  • Conflict detection between documents making contradictory claims about the same code.
  • One runtime dependency (the MCP SDK). 34 tests.

Two bugs worth knowing about

Both were found by running kontext against real repositories, and both are fixed here:

  • init could have rewritten my entire home directory. A project folder with no .git of its own makes findRepoRoot walk upward. On a machine where $HOME is itself a git repo, that landed on $HOME — and init --yes would have rewritten 3,562 markdown files. It now refuses when the root is the home directory or the corpus exceeds 400 documents. --force overrides.
  • Vendored docs were being counted as yours. Run against a real Python project, it reported 13 documents and 3 contradictions — but 12 of those were LICENSE/README files inside .venv, and all 3 contradictions were identical third-party licences noticing they matched each other. Defaults now cover Python, JS framework caches, Pods, Terraform, Gradle and more, unioned with user excludes so they can't be lost by overriding the config.

Known limitations

  • Staleness is proven against git history, so a repo with squashed or rewritten history will under-report drift.
  • describes: globs match tracked files only. Untracked code is invisible to the drift check, by design.

Full detail in CHANGELOG.md · the contract is in docs/SPEC.md.

Assets 2
Loading