sooth n., Old English — truth
soothsay
A soothsayer is, literally, a truth-teller.
Your agent docs make claims.
Soothsay proves them.
$ npx @njtp/soothsay check
02 The problem
Your agent docs are lying.
CLAUDE.md, AGENTS.md, SKILL.md — these files control agent behaviour, yet nothing fails loudly when they drift. They go stale, contradict the repo, and quietly mislead every agent that loads them.
package-manager
docs say npm install
The repo moved to pnpm months ago — package.json#packageManager says so.
command-exists
SKILL.md → scripts/deploy.sh
Deleted in March. The skill still tells agents to run it.
tool-claim-mismatch
prose: "read-only agent"
Frontmatter grants Edit. The description is a wish, not a fact.
freshness
verified=2026-01-01
14 commits touched the watched paths since. Nobody re-read the section.
Code has compilers, tests, and CI. Agent markdown has nothing — and the breakage happens when code changes, not when docs are edited.
03 The proof
Every claim, checked against the repo.
"Never ask a human to restate a fact the repo already states."
$ npx @njtp/soothsay check
CLAUDE.md
✗ L7 [package-manager] `npm install` found but this repo uses pnpm (declared in package.json#packageManager)
→ Use `pnpm install` instead
✗ L9 [command-exists] command references `scripts/deploy.sh` which does not exist
✗ L11 [link-valid] broken link: docs/missing.md does not exist
⚠ L5 [freshness] "Setup" was last verified 2026-01-01, but 3 commit(s) touched package.json since
.claude/agents/reviewer.md
✗ L1 [tool-claim-mismatch] agent claims to be read-only but has the Edit tool
4 error(s), 1 warning(s), 0 info — FAIL
$ npx @njtp/soothsay check
✓ no findings — your docs tell the truth
0 error(s), 0 warning(s), 0 info — PASS
04 The system
Four layers. Deterministic to the core.
Layer 0
Extract & verify
Zero config. Parses your agent docs, extracts every checkable claim — paths, links, commands, package manager, frontmatter, tool-permission claims — and verifies each against repo facts. Value on the first run.
npx @njtp/soothsay check
Layer 1
Freshness
One-line fresh: directives plus git log. Any commit touching a watched path after the verified date flags the section as stale. Re-stamp after human review.
soothsay bless CLAUDE.md
Layer 2
Sidecar asserts
Claims extraction can't parse live in soothsay.yml — outside agent context, zero token tax. Each assert anchors to a real heading; a dead anchor is itself an error, so the sidecar can't silently drift.
soothsay.yml
Layer 3
AI advisory
Opt-in. Budgeted, content-hash cached, Haiku-priced. Finds cross-file prose contradictions and vagueness — and its findings are advisory only. It never blocks CI.
soothsay check --ai
The deterministic core costs $0 forever. The AI pass costs cents, only when asked.
05 The gate
CI that doesn't cry wolf.
Docs break when code changes — so the check belongs next to the tests, on every pull request.
- run: npx @njtp/soothsay check --github
✓Exit 1 only on high-confidence errors. --github puts findings inline on the PR diff; confidence tiering exists precisely so CI doesn't cry wolf.
06 Get started
Make your docs tell the truth.
$ npm i -D @njtp/soothsay
then · npx soothsay check · zero config required
Existing tools lint agent markdown — soothsay proves it.