Topos

Assess a multi-file changeset against a git baseline and roll the per-file verdicts into a project before/after (read-only). Use for a module split or any edit spanning several files. Each file is compared to `baseline_ref` (new files have no baseline). Flags `complexity_relocated_within_file` and `project_regression`. Returns a ChangesetResult.

Compare a baseline to a side-by-side proposed variant (read-only). For normal edit-in-place loops, use `topos_assess_worktree_change` or snapshot first with `topos_begin_refactor` then `topos_assess_snapshot`. This tool is for variants supplied as `proposed_code` or `proposed_filepath`. Returns an AssessmentResult with `status` and score/metric deltas.

Assess the current file against a baseline captured by topos_begin_refactor. Loads the stored baseline by `snapshot_id` and compares it to the current on-disk file, with the same status semantics as `topos_assess_improvement`. A missing or expired snapshot is reported via `blocked_by`.

Assess an in-place edit against a git revision — the common refactor loop. Stateless: the baseline is read from git (`git show <baseline_ref>:<path>`, default `HEAD`) and compared to the current working-tree file. No prior call required. For untracked/new files or an uncommitted pre-edit baseline, use `topos_begin_refactor` + `topos_assess_snapshot`. Do not call if you have not edited the file. A no-change result on a passing file has no `next_tool`.

Persist the file's current source as a baseline snapshot before you edit it (writes a snapshot record — its only side effect). Returns a `snapshot_id`; edit the file in place, then call `topos_assess_snapshot(snapshot_id, filepath)`. Use this when the baseline is not a committed git revision.

Measure how well a test suite exercises its program-under-test, via structural (UAST) coverage (read-only). A standalone signal, separate from the four-pillar quality lattice; for a quality verdict use `topos_evaluate_*` instead. Computes UAST bipartite declaration matching and k-gram path recall. Returns a CoverageResult.

Compute the AST (tree-edit) distance between two source-code strings. Read-only and idempotent; parses both snippets in memory, never writes or scores. Use for clone detection or to measure refactor impact; the `topos_assess_*` tools already fold this in as an anti-gaming check, so call it directly only for the raw number. Returns a ComparisonResult: `normalized_distance` in [0, 1], `similarity` (= 1 - it), `raw_distance`, an `operations` edit-count map, and `source_valid`/`target_valid` (`error` set if either fails to parse).

Compute the AST (tree-edit) distance between two source files on disk. Read-only; parses both files, never writes or scores. Both files are parsed in the language their suffix names, the same way `topos compare` does; an unsupported suffix or two different languages is an error. Use for clone detection or refactor impact; use `topos_assess_*` for a quality verdict. Returns a ComparisonResult (see `topos_compare_code`).

Report `.gitnexus` availability and freshness (read-only). Distinguishes a missing graph from a stale one and from a load/schema failure, so an agent knows whether COMPOSABLE can be trusted and what to do next. Never shells out and never mutates state.

Score a raw code string on the SIMPLE / SECURE / NAVIGABLE quality lattice (read-only; never writes or runs the code). Use for a snippet not yet on disk. SIMPLE, SECURE, and NAVIGABLE are reachable here (CFG/CPG/UAST); COMPOSABLE needs a module dependency graph, so for it use `topos_evaluate_file` with `gitnexus_dir`, or `topos_evaluate_project` for a whole tree. Returns an EvaluationResult: the lattice verdict (SLOP…IDEAL), per-generator scores, and a next-step agent contract.

Score a file on disk on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice — the only evaluate tool that can reach COMPOSABLE (side-effecting). Unless `no_composable` is set, this generates/refreshes `.gitnexus` (given by `gitnexus_dir` or auto-detected at `<root>/.gitnexus`) when it's missing or stale, then attaches the resulting ModuleDependencyGraph — the same default behavior as the CLI's `topos evaluate`. SIMPLE/SECURE/NAVIGABLE always run. When GitNexus isn't installed or generation fails, `coupling_available` is false and `warnings` explains why; the rest of the evaluation still succeeds. Do not call again when `agent_contract.next_tool` is absent: the file already passes, or this call already returned the edit span.

Recursively score every supported source file in a directory on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice, with a project rollup (side-effecting). Autodetects all supported languages in one walk. Returns a summary by default: the rollup (`aggregate_floor_verdict` is the pillars every scored file holds), the five `worst` files with absolute paths and the metric behind each, counts, and warnings. `detail: "full"` returns per-file rows (`limit` / `offset`) and the named lists. Unless `no_composable` is set, generates/refreshes `.gitnexus` when missing or stale before scoring, same as `topos_evaluate_file` and the CLI's `topos evaluate` — `coupling_available`/`warnings` explain it when that isn't possible, without failing the evaluation. Do not call this for one file, or after a file already passed. It walks the tree. A person asks for the project rollup; an agent editing one file does not.

Generate the `.gitnexus` dependency graph via GitNexus (side-effecting). Ensures the graph by default: no-ops when current, otherwise runs `gitnexus analyze`. `force=true` always regenerates.

Return a Topos documentation page as Markdown. Use when your MCP client does not expose resource fetching to the agent. Clients that do surface resources should prefer the equivalent resource URI for efficiency: `topos://docs/{topic}`. Topics: `agent-contract` (compact loop contract, read first for refactors), `lattice` (the 16-element H(G_qual) over four generators), `metrics` (every metric key, thresholds, interpretation), `preferences` (strict generator rankings and preference walks), `priority` (priority profiles), `workflows` (the expanded refactor loop guide).

Full metric breakdown for a single code unit (inline string or file). Provide exactly one of `code` or `filepath`. Use when you need the per-function detail behind a verdict; use `topos_evaluate_*` when the medal alone is enough. Returns an InspectionResult: the lattice `evaluation`, a *top-N* function complexity table (`top_n_functions`, default 10), `total_functions`, and entropy details. With `filepath`, the verdict is scored on all four generators and agrees with `topos_evaluate_file`: unless `no_composable` is set, this generates/refreshes `.gitnexus` (given by `gitnexus_dir` or auto-detected at `<root>/.gitnexus`) when missing or stale, then attaches the ModuleDependencyGraph — so this tool is side-effecting. With inline `code` there is no module to place in the graph, so only SIMPLE/SECURE/NAVIGABLE are reachable, as in `topos_evaluate_code`. Do not call after `topos_evaluate_file` already returned a passing verdict or a `refactor_targets` span. This is the detail view, not the next step.

Structural PR or commit-range recap: gate readiness, blocking findings, files needing attention. Summary by default; `detail: "full"` for `topos.pr_recap.v3`.

Turn a generator ranking into a preference-ordered relaxation walk. Pure and read-only (lattice math only; no files, no scoring). Call after an evaluation to pick the next verdict to aim for, or to relax the goal gracefully under a token/time budget. Returns a PreferenceWalkResult: `walk` (steps from target down to just above `current`), `next_step`, `progress` in [0, 1], `aspirational_target`/`fallback_target`, and `induced_order` (all 16 verdicts ranked).

Rank structural refactor hotspots for one file (read-only, advisory). Does not score the four pillars — use `topos_evaluate_*` for medals and `topos_assess_*` to verify edits afterward. `target` selects the engine: `cycles` (CFG loop/branch bodies), `dependencies` (MDG Forman curvature on imports; needs `.gitnexus`), or `process` (execution choke points; needs `.gitnexus`). Returns a RefactorResult with ranked `hotspots` (`kind`, `label`, `score`, `suggestion`, optional lines).