Verinoda

⚠️ Durum / Status: TAMAMLANMADI — work in progress, no guarantees. Bu depo aktif geliştirme altındadır ve henüz bitmemiştir. Özellikler eksik, değişken veya hatalı olabilir; hiçbir doğruluk, güvenlik ya da uygunluk güvencesi verilmez. Üretimde kullanmayın. This repository is unfinished. Features may be missing, change without notice or be wrong. No warranty or guarantee of correctness, security or fitness for any purpose is given (see also the Apache-2.0 "AS IS" terms in LICENSE). Not published to PyPI yet. Formerly developed under the working name "RepoAtlas".

What is in this snapshot (2026-09-26)

Known limitations (see also docs/DESIGN.md for per-decision gaps):

• A Turkish question about a repository whose code is English but whose UI strings and docs are Turkish (Verinoda itself) finds the Turkish text first: the verinoda_user_tr set scores 13/30 (query text and analyze; 11/30 before an English code word in a Turkish question stopped taking the names it merely appears next to, 2026-09-25), against 36/37 on the English graphify_core. Each dictionary gloss of a Turkish word still counts as its own search term, which is why adding correct dictionary entries has not helped yet. Two fixes were measured and not kept (docs/BENCHMARKS.md, Update 2026-09-25): weighing such words below their translation cost a mod set, where those words are how the data files are found.

• On Windows with Python 3.10 or 3.11, a source file nested thousands of levels deep can crash the extractor: the upstream pipeline raises Python's recursion limit to 10,000, and before Python 3.12 that can exhaust the C stack before a RecursionError (found by CI, 2026-09-25; Python 3.12+ and other systems are not affected).

Open findings of the second acceptance audit (2026-09-23 05:00), not yet fixed:

• Under process isolation a test run can still write outside the throw-away copy through pytest @argsfile or --junitxml indirection; use --isolation container for untrusted code.
• Running scan/init/observe with the home directory itself as the project is not refused.
• Questions that are only partly about the code can come back met with verified but irrelevant claims.
• The reference resolver can still merge or drop references in some multi-reference sentences. Fixed on 2026-09-24: "PR #123 and issue #456 in psf/requests" bound both numbers to the local project's origin remote (an owner/repo after a preposition, or before "reposundaki"/"'teki", is now a repository reference when its sentence is about git objects; fractions, protocols, word pairs and folders such as 1/3, HTTP/2, read/write, services/billing are not); a bare number keeps the origin remote over a repository named in another sentence, and with two repositories in a sentence each number goes to the one written after it. A name right before a version ("fancylib 2.31") is looked up in the project's ecosystems, then PyPI, npm and crates.io, only with --network on; by default it stays unbound, common words and units ("took 2.5 seconds", "macOS 14.2") are never package names, and only a clearly written name ("the X package", a name before v0.3) makes the result partial with a question.
• Fixed after that audit: user claim add --kind with unrelated text no longer verifies; .verinoda/ and .git/ files are no longer accepted as evidence; packaging is now a declared dependency.

Found by running Verinoda on its own repository (2026-09-23), not yet fixed:

• update rebuilds the code graph over the whole corpus when a file of the graph or a new code file changed (unchanged files come from the AST cache): about 33 s on a repository of about 2,100 files, about 27 s on Verinoda's own repository (about 1,200 files), 21 s when the edit leaves the graph as it was (34 s before the per-file caches and the kept graph of 2026-09-25, on the same quiet machine; 44 s before each path was resolved once per build, measured under load) and 94 s on Python's standard library copied as a project (2,305 files, 79,526 nodes; measured before that change), so verinoda ui --watch trails an edit by that much; edits to other files (data files, documents outside the graph) only refresh the search index. The upstream incremental pass was faster (about 20 s) but lost the cross-file edges of every file it re-extracted, so after an edit a function's imports and calls into other files were missing until the next full scan (fixed 2026-09-24). analyze refreshes first without charging it to its 60 s budget; on a project of 300 or more files where the last graph build took over 15 s (or over 200 files changed, or another build is running) it answers from the previous index and names the changed files instead, and the MCP server starts verinoda update in the background. Run verinoda update . when you want the answer on the new code. Two builds of one project never run at once: the second waits (the CLI up to 10 minutes) or, where it may not wait, does nothing and says who is building.
• A frozen copy of the code inside the repository (here benchmarks/corpora/heldout_repoatlas_7371990/) answered self-queries unless it was marked by hand (verinoda setup . --reference benchmarks/corpora=heldout,snapshot). Since 2026-09-24 scan and update find such copies themselves and rank them the same way (see Reference trees); a copy they cannot tell apart from the original still needs --reference. (Fixed on 2026-09-24: command names now map to their handlers, scan komutu -> cmd_scan.)

Game mods and data files (2026-09-24):

• The kind of resource an id names is taken from a fixed table of command words and JSON keys; an id in plain Java is "kind not stated" (an inference) unless one file carries it. Bare names count only as an argument of an id constructor or of a helper whose name says what it loads.

• The extra call pass covers Java and Kotlin only. Turkish stems that folding merges (öl die / ol be) are matched as written only in retrieval; the question plan still reads folded words.

• Windows only so far. The POSIX resource limits and the container isolation path (docker/podman) are coded but have never been run.

• experiment, observe and analyze --run-tests/--observe run the project's own tests. Under process isolation (the default) the command's path arguments are confined to a throw-away copy, but the tests themselves can read and write outside it and use the network. Only run them on code you trust (experiment run --isolation container needs docker/podman and has not been tried against a real one).

• Test runs and observation are Python/pytest only. They use the project's own .venv/venv when it has one, otherwise Verinoda's interpreter; pytest must be installed there, or the run is inconclusive. The fast tracer needs Python 3.12+ (sys.monitoring). The fallback is much slower, and child processes are not traced.

• Precise call resolution is optional (verinoda[precise], jedi) and covers Python only. Without it, method calls on typed parameters stay strong_inference. Other languages need a SCIP index that you produce yourself (scan --scip FILE).

• Turkish questions work but trail English. The Turkish question sets and the intent gold table were written by the rule author, so those scores are in-sample.

• Staleness of relation claims is tracked at the level of the whole calling function, so edits elsewhere in that function can mark a still-true claim stale.

• Some reference mismatch codes fire only in narrow cases, PEP 740 provenance is not used for pinning, and there is no authenticated GitHub access.

• No model-in-the-loop measurement exists. Token counts are chars/4 estimates, and the harness scores whether gold facts are present in the delivered context, not answer accuracy.

The sections below describe the product; where they are ahead of the code, the lists above say so.

Evidence-first codebase analysis for people and coding agents.

Verinoda looks at a repository as a running system: code, call and data flow, tests, configuration, git history, decision records and, when you let it, targeted test runs. It answers questions as claims with evidence. Every claim carries a status (statically_verified, experiment_verified, strong_inference, unknown, stale, …), the exact file:line or commit it rests on, and what is still uncertain. When a claim can't be supported, it says unknown and names the next check to run. Questions may be in English or Turkish. References in them (repositories, versions, packages, PRs, papers) are pinned to the exact version the user meant before anything is compared.

Verinoda is derived from Graphify (commit 20a20d30, Apache-2.0). It is an independent project, not an official Graphify release. See docs/UPSTREAM.md. The name "Verinoda" was checked as free on PyPI, npm and GitHub on 2026-09-23 (see docs/NAMING.md) and again free on 2026-09-26. Packages are published from release tags (docs/RELEASING.md); until the first tag, nothing is on PyPI or npm.

Install

Verinoda is a Python package (verinoda on PyPI, with a small verinoda wrapper on npm). Pick one:

uv tool install --link-mode copy "verinoda[precise]"   # recommended: isolated, uv fetches a Python if needed
pipx install "verinoda[precise]"                       # the same with pipx
pip install "verinoda[precise]"                        # into the current environment (Python 3.10+)
npx -y verinoda --version                              # Node users: runs the PyPI release through uvx / pipx / a private venv
uvx --from "verinoda[precise]" verinoda --version      # run once without installing

On Windows, get uv first with winget install --id astral-sh.uv -e (then open a new terminal) and run uv tool update-shell once so verinoda is on PATH. [precise] adds the optional precise call-site resolver (jedi); leave it out for a smaller install. Upgrade with uv tool upgrade verinoda, pipx upgrade verinoda or pip install -U verinoda. Releases are published from tags by .github/workflows/release.yml (docs/RELEASING.md); if pip says there is no matching distribution, the first release is not out yet - use the development version below.

The development version (main), straight from GitHub:

# Windows (PowerShell or cmd)
uv tool install --force --reinstall-package verinoda --link-mode copy "verinoda[precise] @ https://github.com/ozcinax-star/verinoda/archive/main.zip"

# macOS / Linux (or Git Bash on Windows)
curl -LsSf https://raw.githubusercontent.com/ozcinax-star/verinoda/main/install.sh | sh

Both development-version commands install from the GitHub archive with the optional precise resolver and copy files instead of hardlinking them (so sandboxed agents such as Codex can import the package). Run the same uv tool install ... line, or the script, again to upgrade. The script (install.sh, read it first) installs uv if it is missing, runs that command and uv tool update-shell; options are environment variables: VERINODA_REF (branch, tag or commit; default main), VERINODA_EXTRAS (none to skip the precise extra), VERINODA_NO_MODIFY_PATH=1.

Why there is no irm ... | iex one-liner for Windows: Microsoft Defender blocked powershell -ExecutionPolicy ByPass -c "irm <script url> | iex" for this project's script as Trojan:Win32/Commando.A!ml, a machine-learning verdict on that download-and-run command line (the script file itself was not flagged). The plain uv commands above avoid the pattern.

Then, once per project:

cd my-project
verinoda setup        # index the code + connect Claude Code / Codex if they are installed

verinoda setup is safe to re-run (it updates the index and leaves unchanged skills alone). --agents claude,codex|all|none, --scope user for all projects, --no-mcp. It ends with a first question about the project, built from its most connected function or class, and how to open the graph.

Or skip it and just ask: in a git work tree without an index, the first verinoda query, analyze, trace, map or ui indexes the project once and says so on stderr (never outside a git work tree or in the home folder; VERINODA_NO_AUTO_INDEX=1 turns it off):

cd my-project
verinoda query "where is the discount threshold configured?"   # indexes first, then answers

Other ways to install

Python 3.10+ (3.12+ recommended: the runtime tracer uses sys.monitoring). Graphify (graphifyy) is not required; the extractor is part of this package.

# from a checkout or a wheel you built (uv build)
uv tool install --link-mode copy .                                   # or a wheel path
pipx install ./dist/verinoda-*-py3-none-any.whl
pip install ./dist/verinoda-*-py3-none-any.whl                      # into an existing venv

# optional: precise call-site resolution (jedi)
uv tool install --link-mode copy --with "jedi>=0.19.2,<0.21" .
pip install ".[precise]"

verinoda --version
verinoda doctor

Build the wheel with uv build --wheel (or python -m build --wheel).

Codex on Windows: use --link-mode copy. With uv's default link mode the installed package files are hardlinks into uv's cache. Codex's workspace-write sandbox on Windows could not read them (PermissionError), so the verinoda CLI failed inside Codex while the MCP tools still worked (docs/AGENT-VERIFICATION.md). uv tool install --link-mode copy … (or UV_LINK_MODE=copy) avoids this. verinoda doctor warns when the install is hardlinked or editable (sandbox_readable). On such an install the Codex MCP entry is registered with --profile full: the Codex sandbox may not import the package, MCP is then the way in, and it must serve every tool the skill uses. Reinstall in copy mode and run install again to get the default (core) entry.

Quick start

cd my-project
verinoda setup                           # once: index + agent skills (or `verinoda scan .` for the index only)
verinoda map . --view dataflow           # entry points -> persistence, with limits stated
verinoda ui                              # notes + graph in the browser (local)
verinoda ui --graph                      # ... opened straight on the graph view
verinoda ui --watch                      # ... and kept up to date while you edit
verinoda ui --export --open              # the graph + file notes as one HTML file, no server
verinoda notes --changed                 # your own notes whose code changed since you wrote them
verinoda query "where is the discount threshold configured?"     # plain-text context
verinoda trace create_order_handler OrderRepository.save
verinoda plan draft "Sipariş API'den veritabanına nasıl ulaşıyor?"   # -> .verinoda/plans/plan-001.json
verinoda plan check plan-001.json        # grounds every mention; 0 ready, 2 invalid, 3 needs clarification
verinoda analyze --plan plan-001.json    # or: verinoda analyze "How does an order reach the database?"
verinoda resolve "compare with requests 2.31 sessions.py"        # pin the references first
verinoda observe --for apply_discount    # which tests reach it at runtime (isolated copy)
verinoda resolve-call orders/service.py:22 save                  # precise extra: which definition?
verinoda claim show clm_…                # evidence (with grades), uncertainties, full history
verinoda challenge clm_…                 # adversarial re-check; can only lower confidence
verinoda update .                        # after edits: re-index changed files, mark affected claims stale
verinoda verify clm_…                    # re-check evidence (moved lines are relocated)

Try it on the bundled example: copy examples/orders_app somewhere, git init and commit it, then run the commands above inside the copy. For observe, give the copy a .venv with pytest installed.

Commands

Exit codes: 0 done, 1 error, 2 usage error / invalid plan / blocked command / a trace with no path or an endpoint that does not name one symbol / an impact --target that does not name one symbol, 3 "needs more" (clarification, partial resolution, refused experiment, incomplete observation, no precise answer, an absent name or a lock mismatch in check, a name api did not find, a debug attempt that says stop, a debug strategy that did not settle it; decide check exits 1 on VIOLATED, 3 when something could not be checked and 2 on an error); 4 (check, api): nothing absent, but something asked for was not checked (another language, a file that does not parse). Every command except memory, mcp serve and index accepts --json (plan schema always prints JSON); JSON is compact when stdout is not a terminal.

In CI: commit the decisions folder and name it in verinoda.toml ([decisions] / dir = "docs/decisions"); run verinoda decide check --base origin/main (exit 1 violated, 3 not checked) and verinoda check --diff origin/main (exit 3 an absent name, 4 a changed file it does not read; a clean checkout has nothing changed against HEAD, so check then says nothing_to_check).

Notes and graph view

verinoda ui opens the project as linked notes in the browser, in the manner of Obsidian, built from Verinoda's own index rather than from hand-written notes:

• A note per symbol, source file, document section and data file: qualified name (Wisp.spawn(), search_index.rank()), signature, doc text, the code (highlighted, with line numbers), and its links in sections: defined in, members, calls, called by, extends / implemented by, imports, imported by, references, the data files it names by resource id and the lines that name it, and the claims recorded about it with their status. A link the tool inferred rather than read in the code is marked ?.
• Local graph beside every note (depth 1 to 3; tests, data files and external types can be hidden) and a graph view of the whole project at file level, coloured by folder (or by community), with a filter that highlights matching notes; files with no links ring the linked ones, and a note's links list the project's own code before tests. Both are force-directed: drag, zoom, hover to see a note's neighbours, click to open it.
• The graph in 3D (3D in the graph view, or V): the same files and links laid out in three dimensions and drawn with perspective, no WebGL or library; the flat graph inflates into depth when you switch. Click a file and the camera flies to it; a panel says what it is in words ("extract.py is used by 136 files and uses 42"; a document mentions files, a data file is named by code) and numbers its linked files: 1-9 fly to one, N walks round all of them, Backspace goes back along your trail, F follows the file (the camera circles it), I lights up what a change to it may affect, Enter opens its note. A region (a folder, or a community when coloured by community) is framed with its busiest files and the regions it works with most; [ and ] step through them, and Tour (T) visits the product's own regions first, then tests, examples and docs, one sentence each. P puts the selected file or region on a watch list: a chip at the bottom brings you back to it, a small diamond marks a watched file, and with the local server the page says when a watched file has changed since the index (it looks every 15 seconds; the list stays in your browser). Measured on Python's standard library as a project: about 60 frames a second in Chrome with 1,745 files and 8,259 links.
• Command bar (Ctrl+K), in English or Turkish: focus rank / odak rank flies to a note in 3D, region ui / bölge ui frames a region, impact store / etki store and path parse to rank / yol parse ile rank light up the files concerned, tour, changed, open …, or a question, which is answered as below; with an empty bar it lists what it can do. ? shows every shortcut; Esc undoes one step at a time (the tour, what is lit, the view).
• Search by name (exact, prefix, part of the name, path) or with a question, which runs the same ranking as verinoda query; a file tree; back and forward; Turkish and English; light and dark. A question (three words or more, a question word, or a ?) also offers Answer the question: the passages verinoda query answers with, each with its lines (highlighted, opening the editor), why it was chosen and its note, then the other places found. The search index is never written for it (not in an exported file: it has no code).
• The line a link is written on under each call, import, reference and resource-id link (not for a file edited since the last index: its line numbers would point elsewhere), and open in your editor: every file:line and a button on each note open VS Code, Cursor or VSCodium at that line (chosen at the top of the page).
• Preview on hover: resting the mouse on a link to a note shows its kind, file and line, signature, first doc lines, your note on it, its link counts and the first lines of its code, without leaving the page.
• What changed: Changed in the graph view rings the files edited, added or deleted since the index (what verinoda update would take in) and, in another colour, the files that use them; a note whose file changed since the index says so, since its links and lines may be off.
• Impact and path: Impact on a note lists what may be affected when it changes: what calls, imports, extends or names it, then what uses those, up to three links back (the project's own code first, tests on or off), and turns the local graph into that set; Path… finds the shortest chain of calls, imports and references from the note to another one, or the other way round. In an exported file both work at file level.
• Notes of your own on any symbol, file, section or data unit: plain Markdown (**bold**, `code`, lists, [[Name]] links another note), kept as .md files in .verinoda/notes/ (notes.dir in .verinoda/config.json puts them in a folder you commit). Each note is anchored to the code it was written about (a symbol or section by its fingerprint, found again wherever it moved; a whole file or a data unit by a hash of its lines) and shows its status: up to date, code changed (read it again, then Read it: still right, which anchors it to the code as it is now) or code gone (the symbol was renamed or deleted: edit it onto something else or delete it). The start page lists your notes, the changed ones first; verinoda notes --changed does the same on the command line and exits 1 when any note needs reading again, for CI.

It is local: a standard-library server on 127.0.0.1 (a free port unless --port is given) that answers only requests addressed to that host and port; the page loads nothing from outside (no CDN, fonts or telemetry; Content-Security-Policy: default-src 'none', scripts and styles only from the server). The one thing it writes is your notes: POST /api/usernote needs the random token of that server run, which only the page it serves carries, JSON, and this origin, so another site cannot write through it; --read-only turns writing off. It follows the index: a few seconds after verinoda update (or any rebuild) the open page redraws the note or graph it shows, keeping its scroll position, and says so (an unseen tab looks when it is shown again). verinoda ui --watch also runs verinoda update itself when the project's files change (once the edits stop; one update at a time; while another process builds the index, the watcher skips that round, the page says why, and it tries again at its next look). verinoda ui --graph opens straight on the graph view.

One file, no server. verinoda ui --export [FILE] writes the graph view and a note per source file, document and data file into one HTML file (default .verinoda/index/verinoda-graph.html; about 4.4 MB for Verinoda's own 1,150 files) that opens with a double click, or with --open right away; the command also prints its file:/// address. Checked in Chrome and Edge from file://. It is the same page with its data inside: the graph with its filters and colours, the file tree, each file's links, outline and claims, a file-level local graph and a name search (a symbol opens the note of its file). It holds no code (verinoda ui shows it) and no path of the machine it was made on (the project root and the home folder are taken out of every name); its Content-Security-Policy allows only its own script and style (by hash) and no connections, so it fetches nothing. It is a snapshot: export again after verinoda update. (The index step no longer writes the upstream Graphify graph.html, which loaded vis-network from a CDN when opened, and removes an old one; GRAPHIFY_VIZ_NODE_LIMIT set to a positive number keeps it.)

Limits: the global graph shows at most 2,500 files (the best connected ones, and it says how many it left out); code is read, not edited; the exported file has file notes only (no symbol notes, no code, no question search) and shows your notes read-only.

Measured on Python's standard library copied as a project (2,305 files, 79,526 notes, 140,342 links; Windows 11, headless Chrome): the server starts in 1.6 s, the start page shows in 1.5 s, a search in 0.8 s, a note in 0.5 s; the graph view (1,745 files, 8,249 links) draws in 0.4 s and runs at about 60 frames a second while it settles; impact and path on the most connected notes take under 20 ms. --export writes 9.3 MB in about 6 s. With --watch each look at the tree takes 0.2 s, and an update takes as long as verinoda update (above, Known issues).

Game mods, data packs and other data files

Code often names its data only through strings: a Minecraft mod runs the data-pack function mymod:wisp_death, loads config/mymod.yml, registers the item whose model is assets/mymod/models/item/x.json. Verinoda indexes those files too and follows the strings between them.

• Data files are searchable. Text files the code graph has no node for (.mcfunction, JSON, YAML/TOML/INI/properties configs, SQL, shaders, CSV, Gradle scripts, skipped sources) become data units; configs are split by top-level section. Files it leaves out are listed with the reason (binary, may hold secrets - the graph's own secret rule -, .graphifyignore, dependency or build-output folder, generated output such as results/ or logs/, large generated JSON, minified); doctor counts them and a query names a left-out file whose name matches the question.
• Resource ids link code and data in repositories that are packs or mods (a pack.mcmeta or a Fabric/Quilt/Forge/NeoForge manifest): ns:path ids, #ns:tags, worldgen ids, function ns:x, translation keys "item.ns.x", Identifier.of("ns", "x"), full asset paths, and bare names passed to an id constructor or a helper whose name says what it loads (runFunction(server, "wisp_death")). The context picks the registry (advancement revoke ... only ns:x names an advancement, "parent" a model). Query output shows names: / named by: lines; a link whose namespace is assumed or whose kind the line does not state is marked inferred, and an analyze claim built from it is strong_inference.
• Identical copies of a data file (a data pack shipped twice) rank once, as the copy in the source set; the others are listed as same content:.
• Java and Kotlin calls the extractor drops (a class name that exists twice in the repository, calls through typed variables, Kotlin calling Java) are added when the file's imports or package bind the class, and graded like any call site.
• Callbacks (docs/DESIGN.md D38): a method reference passed on (END_SERVER_TICK.register(RepairScheduler::tick), createTickerHelper(..., Block::serverTick)) is a registers edge, never a call and never weighed by the ranking. trace follows it when no call path exists and labels the hop callback; impact, the UI and review list the method that registers a changed one; a claim "A calls B" that only a method reference supports stays weak_inference. map --view dataflow starts at the mod's entry points (fabric.mod.json, Fabric initializers, @Mod, @SubscribeEvent, mixin handlers, registered callbacks) and knows JVM file writes, NbtIo and dirty flags; all of these are text heuristics, each with its reason.
• Reference trees: verinoda setup --reference original-plugin/=original,plugin keeps an original implementation searchable but ranks it at 0.6x unless the question says "original", "plugin" or the folder name. A folder that holds a copy of the project's own code (a benchmark corpus with an older version, a vendored snapshot) is found at every scan and update and ranked the same way: most of its files have a twin elsewhere defining the same names, nothing outside it uses it, and the twins are in code the project does use (copies.json; index.not_copies or index.detect_copies: false in .verinoda/config.json undo it). A port next to its original with nothing else using either is left to --reference.
• Turkish names from the repository: parallel locale files (lang/en_us.json + lang/tr_tr.json, locales/en.json + locales/tr.json) teach the lexicon that "Fener Asası" is lantern_staff.

examples/glow_mod/ is a small fictional Fabric mod with a data pack, a config file, a reference tree and a copied data pack; its question set (glow_mod, 14 questions, 7 Turkish) was written without running Verinoda on it. Results: docs/BENCHMARKS.md.

Coding agents

verinoda install --agent claude --scope project   # .claude/skills/verinoda/SKILL.md + .mcp.json entry
verinoda install --agent codex  --scope project   # .agents/skills/verinoda/SKILL.md (+ MCP config)
verinoda uninstall --agent claude --scope project # removes only what install recorded

• Claude Code: /verinoda how does checkout reach the database?
• Codex: mention $verinoda in the prompt. (Codex has no /verinoda command.)

The skills describe the working method; all logic lives in the CLI/MCP core. They read the CLI's plain text and add --json only for a field the text leaves out (JSON cost 2-5x the tokens for the same content). Two protocols come first:

1. References the user gives. When the message has links, repository or package names, versions, commits, PR/issue numbers, papers or docs, the agent runs verinoda resolve "<message>" (MCP reference_resolve) before researching or answering. It reports each reference as <name> @ <pin> (basis: …) with each mismatch on its own line. It never substitutes the default branch for a version the user named, asks only the returned questions_for_user, and states every unresolved part with its next step.

2. Understand the question first. verinoda plan draft "<message>" (MCP question_plan_draft). Then the agent edits the plan: it splits compound questions, glosses domain words, copies versions exactly as written, and never invents candidates. Then verinoda plan check: exit 0 ready, 2 invalid, 3 needs clarification. The agent asks only the returned clarifications (AskUserQuestion in Claude Code; request_user_input or plain text in Codex) and records the answers. Then verinoda analyze --plan <file>. The answer starts with "Understood as / Anladığım: …", followed by one block per sub-question with its verdict, claims and unknowns.

3. Check the names code uses (Python). After every edit, and before proposing code, the agent runs verinoda check --diff (MCP code_check; code not written yet: --stdin --as <path>). It never keeps an absent site: it fixes it from nearest / elsewhere or from verinoda api <module.or.Class> (MCP api_members). unknown is unverified, not fine. The report names the environment it checked. It is Python only: a Java, Kotlin or TypeScript file, or one that does not parse, comes back under not_checked (exit 4), and the agent says so instead of reporting a pass.

4. Confirm your own sentences. A sentence the agent writes about the code is recorded with a typed kind (claim add --kind relation|config|order|location --symbol X) or a verbatim quote; plain prose is at most weak_inference, and a not_found name is reported, not replaced.

5. Decisions are the user's. For a should-we / which-one question the agent runs verinoda decide brief, asks the questions_for_human, records the user's explicit choice (decide record) and never picks for them; before finishing a code change it runs verinoda decide check --changed.

6. Keep a debug ledger. debug start before the first edit of a bug fix, debug try --hypothesis after every edit; on stop it stops editing and follows the first strategy, and it asks before changing a test's expectation.

Then the evidence discipline: report claims with their status, never upgrade a status by wording, challenge what you rely on, report unknown with its next step, and treat user critique as a hypothesis (feedback add --process).

How claims stay honest

• Relevant evidence, checked in one place. A *_verified status needs one evidence group that is verifying, fresh and mechanically entails the claim (for example: an AST call to the target at the cited line inside the claimed caller; a definition spanning exactly the cited lines). Every stored status change passes through this check, so unrelated evidence cannot verify a claim on any path (API, verify, feedback, experiments, runtime runs, MCP).
• Word overlap never verifies. Every word of "apply_discount returns the subtotal above the threshold" is in the lines that return subtotal * 0.9 there. Term coverage makes evidence relevant (partial), never a verification; only a verbatim quote (path:12 contains: <text>, which verifies the quoted text and nothing around it) or a kind's typed check (call site, definition span, environment read, call order) verifies. A written claim that states more than its check binds (another callee, a condition or bound, a negation, the arguments of a call, another file than the cited one) stays unverified.
• Every role is bound. A written relation must name the caller and the callee in the right direction ("OrderRepository.save calls place_order" is checked against save's body); a written config claim ("the discount threshold is read from ORDERS_MAX_ITEMS") must be about the name the read is bound to. claim add answers a definitive miss at once, with its scope: "no direct call to save in create_order_handler (orders/api.py:16-21); calls through other names are not followed".
• A name written as code is never replaced by a similar one. analyze, plan check and trace report not_found with did_you_mean ("no symbol named place_orders in this repository; nearest: place_order (orders/service.py:19)"); the sub-question is unmet. A name spelled only in a file changed since the index is "not in the index yet"; one the index spells but has no symbol for (a constant, an attribute) is not_a_symbol, with where it occurs. trace, map --view impact and node_inspect share one resolver: a detected copy of the project gives way to the original, test, example, fixture and vendored code to the product's own, and a name that several symbols still carry is listed, not picked (pass path/file.py::Name).
• A stale index is never silent. Reading commands list the files changed since the index; analyze says when it answered from the previous index, and a changed file that spells the question's subject caps that sub-question at met_with_inference.
• A graph edge (EXTRACTED/INFERRED) is never enough on its own. Search results, model summaries and user feedback are not even support for an inference. A claim with no evidence is unknown.
• Definitive vs heuristic refutation. Only an exhaustive check within a stated scope (no call to the target on the cited line, a precise resolver's definitive different target, …) makes a claim contradicted. A heuristic doubt lowers it one step and adds an uncertainty.
• Facet-level staleness. Claims depend on symbol facets (signature, body, name bindings, doc sections, the test set). An edit makes a claim stale on the next update/analyze only if something it depends on changed. Code that only moved is relocated through anchors, and a duplicated line is reported ambiguous rather than guessed.
• Critique and re-verification never raise a claim above its assessed ceiling. Critique is idempotent and never restores a stale or contradicted claim.
• Runtime observations are run-scoped ("observed in run R at commit C"). They never support an "always" claim, and calls seen through test doubles never support production edges.
• Nothing is deleted: user corrections supersede (the old claim is kept as contradicted with superseded_by), claim text is immutable, and history, plans, reference resolutions and runtime runs are append-only.
• Heuristics state their method and limits (coverage.limits, uncertainties, derived_by). Budget exhaustion or irrelevant retrieval yields unknown with the next verification step.

Name check (Python)

verinoda check answers one question for code an agent (or you) just wrote: do the modules, functions, methods, keyword arguments and dict keys it uses exist, in this project's environment?

$ verinoda check orders/ai/export.py
orders/ai/export.py:7:28  ABSENT  import orders.service.place_orders
    not found in module orders.service in this project (orders/service.py)
    nearest: place_order (orders/service.py:19)
orders/ai/export.py:15:43  ABSENT  kwarg compute_total(currency=)
    keyword currency= not found in the signature compute_total(items: list[dict]) (orders/pricing.py:6)
orders/ai/export.py:19:10  unknown  attribute repo.save_order
    `repo` is a parameter: its runtime type is not known

• Which environment: --env PATH, else the project's .venv, venv or env when its base interpreter is a known Python installation outside the project (otherwise the note names the program --env .venv would start), else Verinoda's own interpreter for the standard library only: third-party names are then not_installed, never absent. The MCP tools never start a program from the project.
• When it says absent: only when the container's names are all known (a module without __getattr__ or dynamic writes, a class without descriptors or code that sets attributes from outside, an instance made right there, one known signature without **kwargs, the dict literals a function returns), and jedi also found nothing. The wording is "not found in as installed in ()", never "does not exist".
• Unknown is not fine: parameters, annotations, inferred return values, **kwargs, module __getattr__, names assigned elsewhere, sys.path changes in conftest.py, and standard-library names of another platform or Python version (collections.Mapping) stay unknown with the reason.
• What it does not read is never a pass: a file in another language, a notebook, a Cython file or a Python file that does not parse is listed under not_checked with the reason; with nothing absent the exit is 4 (3 means an absent name or a version that differs from the lock).
• verinoda api packaging.specifiers.SpecifierSet lists the real members before a call is written. Existence and signature shape only: a real name used wrongly is not detected.

Documentation

• docs/ARCHITECTURE.md — modules, state on disk, invariants
• docs/DESIGN.md — design decisions D1-D40 and their implementation status
• docs/BENCHMARKS.md — measured comparison (no unmeasured savings claims)
• docs/UPSTREAM.md — Graphify base commit, feature inventory, port method, runtime patch
• docs/UPGRADING.md — versioning, schema migrations, calibration changes, derived files
• docs/AGENT-VERIFICATION.md — what was verified with the real agents
• docs/GENEL-BAKIS.md — Türkçe genel bakış (ürün sahibi için)
• docs/NAMING.md — name availability
• docs/RELEASING.md — how a release reaches PyPI, npm and GitHub

License

Apache-2.0 (see LICENSE); portions originally under MIT (LICENSE-MIT). NOTICE records the Graphify origin and the modifications.