| name | world-model-ledger |
| description | One-time SETUP: installs a persistent SQLite-backed WORLD MODEL for a coding agent into a project (or global ~/.claude). Use when the user wants an agent to remember a codebase across sessions, detect contradictions, propose fixes, and improve correctness over time — "give the agent a world model", "track what's verified vs assumed", "persist codebase knowledge with confidence". Tracks entities (symbols/files/modules/external referents), interactions, and constraints with TWO confidence axes (observed vs normative), validation status, and PROV-style evidence. Load-bearing rule: code observation is NOT ground truth — only oracle evidence (tests/CI/docs/human) raises normative confidence, flagging observed-but-unverified. Every triple is checked against a predicate ontology (RDFS-style domain/range) before insert — hallucinated verbs and impossible pairings are rejected, not stored. Zero-config capture via four hooks (PreToolUse pre-edit summaries; UNIVERSAL PostToolUse observing every tool call; Stop/SessionStart consolidate + inject digest, auto-bootstrap); invoke ONCE; hooks run automatically. Not a linter, LSP server, RAG vector store, or model-driven fact extractor. |
| license | MIT |
| compatibility | Requires Claude Code lifecycle hooks (PreToolUse/PostToolUse/Stop/SessionStart), bash, and python3 with its stdlib sqlite3 (no pip, no network); jq optional for clean settings.json merging. |
| x-spec-version | 1 |
| metadata | {"author":"dhanesh","version":"1.1.0","tags":"claude-code,hooks,world-model,sqlite,memory,confidence,provenance,contradictions,ontology"} |
world-model-ledger
A persistent world model for a coding agent, backed by SQLite. It records what the agent
learns about a codebase — entities (symbols / files / modules / real-world referents), the
interactions between them, and the constraints that should hold — and, for every
interaction and constraint, how sure we are it exists, how sure we are it is correct,
whether it has been validated, and what evidence backs it.
The defining rule, enforced as an invariant: code-observed relationships are not ground
truth. A file sighting can drive observed_conf to 1.0 while normative_conf stays 0 and
status stays unverified. Only oracle evidence — a passing test, CI, a doc, a human — raises
normative confidence. See references/confidence-model.md for the epistemics and
references/schema.md for the data model. The design rationale is in
docs/superpowers/specs/2026-07-01-world-model-ledger-design.md.
Install & operate
Detect the install state first — before asking anything. The skill is already installed if
~/.claude/world-model-ledger/wm.py exists (GLOBAL) or ./wm.py + ./world_model.py exist in
the project (PROJECT). Then route by how you were invoked; the full flag table is in
references/parameters.md.
--seed / --prune — operate on an existing install (NO scope question, NO re-install)
If the skill is already installed and you were asked to seed or prune, do exactly that
against the current repo and stop — do not run the full installer and do not ask which
scope to use (that decision was already made at install time):
scripts/install.sh --seed
scripts/install.sh --prune
These short-circuit to python3 "$WM/wm.py" build . [--prune] (where $WM is . for a
project install, else ~/.claude/world-model-ledger), create and gitignore .world-model/,
and report entities_added / interactions_added. They are idempotent — safe to re-run
anytime on an installed model.
