# Reported issues for Topos

Pod holds 20 of 40 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Topos](/mcp/topos).

## Most discussed

### Project agent_contract routes to inspect_code, not evaluate_file on the ROI head

## What

After `topos_evaluate_project`, `agent_contract.next_tool` is `topos_inspect_code`. For "find the cheapest structural win in this repo", the useful next call is `topos_evaluate_file(refactor_targets=…)` on a ranked head, then inspect only if that is insufficient.

Compounding it, `worst_files` ranks by ascending minimum score across dimensions. On a repo with many leaf modules at `mdg.instability = 0.0`, COMPOSABLE zeros flood the head of the list, so the "start here" pick is often a fi

[Read the thread](https://github.com/Krv-Labs/topos/issues/234) · 2026-07-25 · closed · 3 comments

### Package Topos as an Agent Plugins 1.0 portable plugin

## Summary

Ship Topos as a portable [Agent Plugins](https://agent-plugins.org/) package so compatible clients can discover and load the Topos skill + MCP server from one vendor-neutral layout.

Spec: https://agent-plugins.org/ (v1.0.0)
Author guide: https://agent-plugins.org/plugin-authors

## Why

Topos already ships:

- Agent Skill at `skills/topos/SKILL.md` (ClawHub / OpenClaw / Hermes)
- MCP via `topos mcp` and `topos install`

Those are client-specific install paths. Agent Plugins defines 

[Read the thread](https://github.com/Krv-Labs/topos/issues/310) · 2026-08-07 · open · 2 comments

### methods: Graphify Phase 2 — robust integration, inflation/drift measures, and agent workflow

## Context

Follow-up to [#150 Graphify Incorporation](https://github.com/Krv-Labs/topos/issues/150) (closed by #159 after **Phase 1**). v0.4.0 ships orphan/fragile-edge detection over `graphify-out/graph.json`, plus `topos graphify generate|orphans`, `topos_generate_graphify_graph`, and `topos_refactor(target="graphify")`. All Graphify signals remain **advisory** — they never feed SIMPLE/COMPOSABLE/SECURE scoring (see [`docs/decisions/refactor-suite.md`](docs/decisions/refactor-suite.md)).

Ori

[Read the thread](https://github.com/Krv-Labs/topos/issues/237) · 2026-07-25 · closed · 2 comments

### agent_contract is built by four independent builders that duplicate flag logic

## What

`AgentContract` is constructed in four separate places that each re-implement the same non-COMPOSABLE flag logic, plus inline literals in a fifth:

| Builder | Location |
|---|---|
| `build_agent_contract` | `topos/mcp/src/formatting.rs` (evaluate_code / evaluate_file / inspect_code) |
| `project_contract` | `topos/mcp/src/tools/evaluate.rs` |
| `assessment_contract` | `topos/mcp/src/tools/assess.rs` |
| `changeset_contract` | `topos/mcp/src/tools/assess.rs` |
| inline literals | `topos

[Read the thread](https://github.com/Krv-Labs/topos/issues/233) · 2026-07-25 · closed · 2 comments

### Publish topos-engine, topos-mcp, and topos CLI to crates.io

## Status: blocked

**Blocker:** `topos-mcp` depends on [Sighthound](https://github.com/Corgea/Sighthound) via a **git-only** dependency (`rev = 36dd5da…`). [crates.io does not allow unpublished git dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories) — `cargo publish --dry-run -p topos-mcp` fails with `no matching package named sighthound found` on crates.io.

**Unblock options (pick one):**
1. Publish `sighthound` t

[Read the thread](https://github.com/Krv-Labs/topos/issues/149) · 2026-07-13 · open · 2 comments

### Feature Request: Expose GitNexus detect_changes in MCP Layer

# Feature Request: Expose GitNexus `detect_changes` in MCP Layer

## Description
Currently, the *topos* MCP integration generates the `.gitnexus/` knowledge graph but lacks automated awareness of structural drift between the graph and the actual filesystem state. We should expose `gitnexus detect_changes` as a new MCP tool to enable proactive diagnostic feedback.

## Suggested Changes
1. **Add `topos_check_graph_drift` tool**: Create a new tool in the MCP server that executes `gitnexus detect_ch

[Read the thread](https://github.com/Krv-Labs/topos/issues/138) · 2026-07-12 · closed · outside contributor · 2 comments

### Feature: GitHub badge for Topos medal counts / distribution

## Summary

Add a **GitHub badge** (shields.io-style or native GitHub integration) that surfaces Topos evaluation results for a repository at a glance—either a **gold medal file count** or a **medal distribution** breakdown.

## Motivation

Topos classifies each file on the evaluation lattice (🥇 GOLD / 🥈 SILVER / 🥉 BRONZE / ❌ SLOP). Today, seeing project-wide quality requires running `topos evaluate project` locally or via CI. A badge would:

- Make structural quality visible on the README and r

[Read the thread](https://github.com/Krv-Labs/topos/issues/81) · 2026-06-27 · closed · 2 comments

### [Feature Request] Print code snippets of dangerous calls and security findings in CLI output

## Summary

When the CLI reports a SECURE failure, it only shows aggregate counts (`cpg.dangerous_calls: 1.000`, `cpg.taint_flows: 0.000`) without telling the user **where** in the code the problem is. The MCP layer already has the data to produce line-level findings — the CLI just doesn't use it.

## Current behavior

```
$ topos evaluate src/
...
secure: [████░░░░░░]  50.0%  (req 100%)  ✗ FAIL
  cpg.dangerous_calls: 1.000
  cpg.taint_flows: 0.000
```

The user sees _that_ something failed, but

[Read the thread](https://github.com/Krv-Labs/topos/issues/58) · 2026-06-10 · closed · 2 comments

## Most recent

### release: v0.5.1 binary ships with rmcp 2.2 (breaks MCP discovery; needs v0.5.2 release)

### Summary
The `v0.5.1` release binary was built with `rmcp 2.2`, which drops the connection when MCP clients (e.g., Google Antigravity / Gemini CLI) send `server/discover` during initial handshake.

### Status
- Fixed on `main` via PR #324 / PR #337 (upgraded to `rmcp 3.1.2`).
- The installer script (`https://docs.krv.ai/topos/install.sh`) still downloads the `v0.5.1` binary which predates the fix.

### Resolution
Cut a new release (e.g. `v0.5.2`) from `main` so users installing via `install.s

[Read the thread](https://github.com/Krv-Labs/topos/issues/346) · 2026-08-24 · open · 1 comment

### perf: topos_inspect_code parses the same source ~4x (measure before fixing)

Surfaced while implementing #306 ([#319](https://github.com/Krv-Labs/topos/pull/319)).

## What

#306 fixed morphism duplication *within* `build_metric_locations`. The remaining duplication is *across* modules. On one `topos_inspect_code` request, four independent `ProgramMorphism` constructions run over the same source:

- `classify_code_string` / `classify_file` — `topos/mcp/src/evaluation/classify.rs:63`
- `overlay_for_source` — `topos/mcp/src/diagnostics.rs:123`
- `security_findings::cpg_for

[Read the thread](https://github.com/Krv-Labs/topos/issues/322) · 2026-08-09 · open · 1 comment

### methods: Graphify-backed NAVIGABLE refactoring guidance

## Context

v0.5.0 added **NAVIGABLE** as the fourth evaluation pillar ([#280](https://github.com/Krv-Labs/topos/pull/280)), measuring agentic cognitive load via Semantic Compositional Divergence (`nav.max_function_divergence`) over the UAST scope tree. When the gate fails, `topos_evaluate_file` already surfaces actionable `refactor_targets` — worst functions first, real line spans, `extract_helper` / `split_decision_logic` operations — derived entirely from intra-file AST evidence.

Separately,

[Read the thread](https://github.com/Krv-Labs/topos/issues/316) · 2026-08-08 · closed · 0 comments

### Reuse parsed morphisms when building metric locations

## Problem

`topos/mcp/src/metric_locations.rs` can construct `ProgramMorphism` more than once for the same single-file request while resolving offending and diverging functions. SIMPLE and NAVIGABLE location generation can therefore repeat parsing/UAST construction.

The duplication is bounded to single-file paths, so it is not a v0.5.0 blocker, but it is avoidable work on the interactive agent path.

## Proposed change

Build one parsed morphism/UAST per request and pass shared references to m

[Read the thread](https://github.com/Krv-Labs/topos/issues/306) · 2026-08-06 · closed · 0 comments

### `@mcp` gallery install does not bind Topos to the current VS Code workspace root

## Summary

The VS Code `@mcp` gallery install of `io.github.Krv-Labs/topos` is often unusable because it does **not** bind Topos to the **current window's workspace folder**.

This is **not** a request for multi-project-at-once analysis. The intended UX is sequential single-repo use across different VS Code windows:

1. Window on `erdos` → Topos evaluates `erdos`
2. Later, window on `topos` → Topos evaluates `topos`

That is **one project per server process, at different times**. Topos already 

[Read the thread](https://github.com/Krv-Labs/topos/issues/293) · 2026-08-06 · closed · 1 comment

### `--gitnexus-dir` at a not-yet-created store skips COMPOSABLE generation, and the CLI reports nothing

Found while dogfooding #275 (v0.4.4 release train). Two related problems, both on the `--gitnexus-dir` path extended by #258.

## 1. Generation never runs when the store does not exist yet

`depgraph_status` classifies an override pointing at a missing path as `invalid_dir` (via `check_override_warning`, `topos/mcp/src/evaluation/mod.rs`), and `ensure_gitnexus_dir_with_progress` treats `invalid_dir` as "a problem generating won't fix" and returns early. So passing `--gitnexus-dir` at a store tha

[Read the thread](https://github.com/Krv-Labs/topos/issues/287) · 2026-08-04 · closed · 0 comments

### Upgrade Topos MCP server to MCP 2026-07-28 (stateless protocol) via rmcp 3.x

## Summary

Upgrade `topos-mcp` from the pre-stateless MCP lifecycle (`rmcp` **2.2**, initialize handshake) to the stable **MCP `2026-07-28`** revision (stateless-by-default) via **`rmcp` 3.x**.

This is a protocol/SDK migration, not a tool-semantics redesign. Keep the existing agent contract (tools, resources, prompt, flat args, compact structured content) unless the wire model forces a small adapter change.

## Background (facts)

On **2026-07-28**, MCP published the next stable specification.

[Read the thread](https://github.com/Krv-Labs/topos/issues/264) · 2026-07-30 · closed · 1 comment

### Treat --gitnexus-dir / gitnexus_dir as COMPOSABLE project root

## Summary

`--gitnexus-dir` / MCP `gitnexus_dir` currently only select the `.gitnexus` **store path**. COMPOSABLE freshness fingerprinting and `gitnexus analyze` (via `topos depgraph generate` / auto-refresh) always use the **CLI process cwd** or **MCP file root** as the project root.

That makes this natural workflow fail or hang:

```bash
# from $HOME — wants to evaluate phil only
topos evaluate ~/krv/open-source/phil/phil/magic -r --language python \
  --gitnexus-dir ~/krv/open-source/phil/.

[Read the thread](https://github.com/Krv-Labs/topos/issues/258) · 2026-07-28 · closed · 0 comments

### Feature Request: Support Automated Agent/Harness Install + Uninstall from CLI

### What do you want?

easy `topos install` & `topos uninstall` support with interactive selection from the CLI

### Why?

Inspired by [skills.sh](skills.sh) UI and our existing `TTY` support in the CLI, would be great to select agent harnesses to install Topos in. Makes cross-agent install and maintenance across a development stack much easier.

### Proposed solution
(note mock-ups are not representative of supported harnesses or MCP-required file changes)
#### Simple CLI Install Mock-Up
```zsh

[Read the thread](https://github.com/Krv-Labs/topos/issues/256) · 2026-07-27 · closed · 1 comment

### scores and pillars can disagree on project rows (raw vs overlay-adjusted)

## What

On `ProjectFileEntry`, `scores.secure` and `pillars.secure.score` can report different values for the same file — e.g. `scores.secure = 62.5` next to `pillars.secure.score = 100.0`.

## Why

In `evaluate_single_file` (`topos/mcp/src/tools/evaluate.rs`, the `ProjectFileEntry` construction):

- `scores` is built from `result.scores` — the **raw** classification.
- `pillars` is built by `build_pillars(&result_for_rollup, …)`, where `result_for_rollup` comes from `adjusted_result`, which **

[Read the thread](https://github.com/Krv-Labs/topos/issues/232) · 2026-07-25 · closed · 0 comments

### Hardening: resolve_within_root lexical fallback weakens symlink containment

_From the review of #159 (Rust v0.4.0 migration). Non-blocking (hardening)._

**Where:** `topos/mcp/src/security.rs` — `resolve_within_root`

**What:** `joined.canonicalize().unwrap_or_else(|_| normalize(&joined))`. `canonicalize` only succeeds when the *entire* path exists; for a non-existent leaf it falls back to lexical `normalize`, which does **not** resolve symlinks. Python's `is_within_root` used `path.resolve(strict=False)`, resolving symlinks on the existing prefix even when the final co

[Read the thread](https://github.com/Krv-Labs/topos/issues/215) · 2026-07-24 · closed · 0 comments

### v0.4.0: topos depgraph generate removed but still referenced — VS Code command broken

## Summary

PR #159 (`worktree-rust-migration-v0.4.0`) removes the standalone `topos depgraph` CLI subcommand, but user-facing surfaces still instruct users (and agents) to run `topos depgraph generate`. On the v0.4.0 binary this fails immediately:

```bash
$ topos depgraph generate
error: unrecognized subcommand 'depgraph'
```

COMPOSABLE graph generation still works indirectly — `topos evaluate` and MCP evaluate tools call the shared `ensure_gitnexus_dir` path (shelling out to `gitnexus analyz

[Read the thread](https://github.com/Krv-Labs/topos/issues/206) · 2026-07-24 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/Krv-Labs/topos/issues).