{"id":"6f06b487-428e-4d51-9db4-138c02812cde","entityType":"agent","slug":"clawhub-krv-labs-topos","name":"topos","canonicalUrl":"https://www.xpersona.co/agent/clawhub-krv-labs-topos","canonicalPath":"/agent/clawhub-krv-labs-topos","generatedAt":"2026-10-10T14:45:02.782Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T12:21:57.674Z","emptyReason":null},"description":"Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals. Skill: topos Owner: krv-labs Summary: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals. Tags: latest:1.0.16 Version history: v1.0.16 | 2026-10-10T11:59:37.827Z | auto - Bumped version to 0.9.0. - Removed the file skill-card.md. - Updated SKILL.md content for accuracy and alignment with current functionality. - No breaking changes to us","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s175s3223xzg0re6x5nrn7vra18ayje0:topos","sourceUrl":"https://clawhub.ai/krv-labs/topos","homepage":"https://clawhub.ai/krv-labs/skills/topos","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/krv-labs/topos","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/krv-labs/skills/topos","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals. Skill: topos Owner: krv-lab"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T12:21:57.674Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T12:21:57.674Z","emptyReason":null},"stars":null,"forks":null,"downloads":1435,"packageName":null,"latestVersion":"1.0.16","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T12:21:57.673Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T12:21:57.674Z","lastCrawledAt":"2026-10-10T12:21:57.673Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T12:21:57.673Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.16","createdAt":"2026-10-10T11:59:37.827Z","changelog":"- Bumped version to 0.9.0. - Removed the file skill-card.md. - Updated SKILL.md content for accuracy and alignment with current functionality. - No breaking changes to usage or dependencies.","fileCount":2,"zipByteSize":5653},{"version":"1.0.15","createdAt":"2026-10-09T14:12:17.195Z","changelog":"- Skill version bumped from 0.7.0 to 0.8.0. - Documentation updated in SKILL.md for accuracy and clarity. - Obsolete file skill-card.md removed. - No functional or API changes; all updates are documentation and metadata only.","fileCount":3,"zipByteSize":6824},{"version":"1.0.14","createdAt":"2026-09-30T09:39:17.269Z","changelog":"topos 1.0.14 changelog: - Updated SKILL.md to reflect version 0.7.0 and revised documentation. - No functional or CLI changes; documentation and version metadata updated. - Maintains requirements, risk notes, and all prior usage instructions.","fileCount":3,"zipByteSize":6809},{"version":"1.0.13","createdAt":"2026-09-30T09:29:34.546Z","changelog":"- Removed the file: skill-card.md - Updated SKILL.md with a revised CLI Reference section, adding details on `topos config` and the new `topos pr-recap` command for pull request quality gates - No changes to skill logic or dependencies - Documentation improvements for configuration and PR evaluation usage","fileCount":3,"zipByteSize":6817},{"version":"1.0.12","createdAt":"2026-09-16T12:21:27.476Z","changelog":"- Bumped version to 0.6.0. - Removed obsolete file: skill-card.md. - Documentation and metadata updates in SKILL.md. - No functional or CLI/API changes documented in this version.","fileCount":3,"zipByteSize":6266},{"version":"1.0.11","createdAt":"2026-08-11T15:41:46.960Z","changelog":"- Documentation updated in SKILL.md; improved references and clarity. - Obsolete or redundant skill-card.md file removed. - No effect on skill logic or runtime behaviorβ€”change is documentation-only. - Version remains at 0.5.1.","fileCount":3,"zipByteSize":6292},{"version":"1.0.10","createdAt":"2026-08-09T03:57:04.266Z","changelog":"## topos v1.0.10 - Updated SKILL.md: version bumped from 0.5.0 to 0.5.1. - Removed skill-card.md file. - No functional or user-facing changes documented; documentation and metadata update only.","fileCount":3,"zipByteSize":6306},{"version":"1.0.9","createdAt":"2026-08-08T16:46:22.626Z","changelog":"**Topos 1.0.9 changelog** - Added a new \"NAVIGABLE\" pillar for code quality analysis; scoring now covers four pillars: SIMPLE, COMPOSABLE, SECURE, and NAVIGABLE. - Upgraded the medal system: ultimate goal is now PLATINUM (was GOLD); GOLD now requires three pillars, PLATINUM requires all four. - Expanded and clarified agent and CLI usage guidance, including new pillar logic and updated references to PLATINUM/GOLD targets. - Documented changes to the lattice structure and medal ranking for v0.5.0; added instructions for updating project preferences for all four pillars. - Removed obsolete skill-card.md file.","fileCount":3,"zipByteSize":6350}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175s3223xzg0re6x5nrn7vra18ayje0:topos","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T14:45:02.778Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-krv-labs-topos/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T12:21:57.674Z","emptyReason":null},"readme":"Skill: topos\n\nOwner: krv-labs\n\nSummary: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\n\nTags: latest:1.0.16\n\nVersion history:\n\nv1.0.16 | 2026-10-10T11:59:37.827Z | auto\n\n- Bumped version to 0.9.0.\n- Removed the file skill-card.md.\n- Updated SKILL.md content for accuracy and alignment with current functionality. \n- No breaking changes to usage or dependencies.\n\nv1.0.15 | 2026-10-09T14:12:17.195Z | auto\n\n- Skill version bumped from 0.7.0 to 0.8.0.\n- Documentation updated in SKILL.md for accuracy and clarity.\n- Obsolete file skill-card.md removed.\n- No functional or API changes; all updates are documentation and metadata only.\n\nv1.0.14 | 2026-09-30T09:39:17.269Z | auto\n\ntopos 1.0.14 changelog:\n\n- Updated SKILL.md to reflect version 0.7.0 and revised documentation.\n- No functional or CLI changes; documentation and version metadata updated.\n- Maintains requirements, risk notes, and all prior usage instructions.\n\nv1.0.13 | 2026-09-30T09:29:34.546Z | auto\n\n- Removed the file: skill-card.md\n- Updated SKILL.md with a revised CLI Reference section, adding details on `topos config` and the new `topos pr-recap` command for pull request quality gates\n- No changes to skill logic or dependencies\n- Documentation improvements for configuration and PR evaluation usage\n\nv1.0.12 | 2026-09-16T12:21:27.476Z | auto\n\n- Bumped version to 0.6.0.\n- Removed obsolete file: skill-card.md.\n- Documentation and metadata updates in SKILL.md.\n- No functional or CLI/API changes documented in this version.\n\nv1.0.11 | 2026-08-11T15:41:46.960Z | auto\n\n- Documentation updated in SKILL.md; improved references and clarity.\n- Obsolete or redundant skill-card.md file removed.\n- No effect on skill logic or runtime behaviorβ€”change is documentation-only.\n- Version remains at 0.5.1.\n\nv1.0.10 | 2026-08-09T03:57:04.266Z | auto\n\n## topos v1.0.10\n\n- Updated SKILL.md: version bumped from 0.5.0 to 0.5.1.\n- Removed skill-card.md file.\n- No functional or user-facing changes documented; documentation and metadata update only.\n\nv1.0.9 | 2026-08-08T16:46:22.626Z | auto\n\n**Topos 1.0.9 changelog**\n\n- Added a new \"NAVIGABLE\" pillar for code quality analysis; scoring now covers four pillars: SIMPLE, COMPOSABLE, SECURE, and NAVIGABLE.\n- Upgraded the medal system: ultimate goal is now PLATINUM (was GOLD); GOLD now requires three pillars, PLATINUM requires all four.\n- Expanded and clarified agent and CLI usage guidance, including new pillar logic and updated references to PLATINUM/GOLD targets.\n- Documented changes to the lattice structure and medal ranking for v0.5.0; added instructions for updating project preferences for all four pillars.\n- Removed obsolete skill-card.md file.\n\nv1.0.8 | 2026-08-04T23:42:26.995Z | auto\n\n- Updated agent loop and CLI instructions for COMPOSABLE project root: added clearer documentation for using --gitnexus-dir and its effect on project root selection.\n- Changed MCP setup instructions: now recommend topos install --all and topos status commands.\n- Bumped version from 0.4.3 to 0.4.4.\n- Removed outdated skill-card.md file.\n\nv1.0.7 | 2026-07-28T21:34:07.798Z | auto\n\n- Updated SKILL.md metadata: version bumped from 0.4.2 to 0.4.3.\n- Documentation or metadata changes only; no functional updates described.\n- Removed the redundant file: skill-card.md.\n\nv1.0.6 | 2026-07-28T07:32:20.391Z | auto\n\ntopos 1.0.6 changelog:\n\n- Updated documentation in SKILL.md to clarify correct usage, CLI and MCP project root handling, and advisory on COMPOSABLE scoring and file root settings.\n- Expanded CLI reference with explicit commands, pillar overrides, and evaluation details.\n- Removed outdated skill-card.md file.\n\nv1.0.5 | 2026-07-26T09:28:32.102Z | auto\n\n- Bumped version in SKILL.md from 0.4.1 to 0.4.2.\n- Removed skill-card.md file.\n- No user-facing functional or documentation changes.\n\nv1.0.4 | 2026-07-26T08:33:04.076Z | auto\n\n- Updated SKILL.md to change the installation command for Topos from `sh` to `bash` for improved compatibility.\n- Removed the file skill-card.md.\n\nv1.0.3 | 2026-07-25T06:47:59.366Z | auto\n\n- Incremented version from 0.4.0 to 0.4.1 in SKILL.md.\n- Removed the skill-card.md file.\n- No functional or content changes to core documentation; maintenance update only.\n\nv1.0.2 | 2026-07-25T06:19:43.361Z | auto\n\n- Improved SKILL.md with expanded documentation on requirements, dependencies, supported platforms, and deployment geography.\n- Added sections covering use case, known risks and mitigations, skill output formats, and explicit notes about credential requirements.\n- Updated metadata to clarify OS compatibility and include an emoji.\n- Removed outdated skill-card.md file.\n- No changes to tool commands or agent loop behavior.\n\nv1.0.1 | 2026-07-25T05:36:56.864Z | auto\n\nTopos 0.4.0 is a feature update with improved COMPOSABLE scoring automation and expanded MCP/CLI details.\n\n- COMPOSABLE scoring is now enabled by default; `.gitnexus` is auto-generated if missing (requires npm gitnexus).\n- CLI and MCP documentation expanded: clarified command/argument differences, updated examples, and referenced new tools (`topos_assess_changeset`, `topos_evaluate_code`, `topos_generate_graphify_graph`).\n- Removed instructions referencing manual graph generation as a default stepβ€”now only needed to force-refresh.\n- Skill metadata version bumped to 0.4.0.\n- Guidance on advisory tools, input arguments, and CLI/MCP limitations improved.\n- Removed obsolete file: skill-card.md.\n\nv1.0.0 | 2026-07-21T10:51:00.861Z | auto\n\n- Initial release of the Topos skill for structural code quality analysis and refactor loops.\n- Scores code along three pillars (SIMPLE, COMPOSABLE, SECURE) and maps results to a medal lattice (SLOP β†’ GOLD).\n- Provides both CLI and MCP commands for measurement, inspection, and verification of agent-written code.\n- Includes guidance for iterative improvement, refactor verification, and common pitfalls.\n- Offers prerequisites and deployment steps along with a detailed reference for both human and tool usage.\n\nArchive index:\n\nArchive v1.0.16: 2 files, 5653 bytes\n\nFiles: SKILL.md (12517b), _meta.json (125b)\n\nFile v1.0.16:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.9.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority --pr-preset ` | View or persist project priority, preference, and PR gate settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos pr-recap [] [--strict] [--preset ] [--verbose] [--info] [--json]` | Judge a PR or git range against the `[pr_recap]` gates: READY / NEEDS ATTENTION / BLOCKED, exit 1 on BLOCKED (and on NEEDS ATTENTION under `fail_on = \"warn\"`); `--json` emits `topos.pr_recap.v3` |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`) β€” never affects the medal |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **Moving code is not a regression in `pr-recap`.** A pillar lost only because code moved into a file is reported under the `moved_pillar` gate (info by default, warn under strict), naming the source file; a moved function that grew on the way is still `pillar_lost`. Set aside a known finding with a `[[pr_recap.waive]]` entry (`gate`, `path` glob, required `reason`, optional `expires = \"YYYY-MM-DD\"`): it stays in the report, marked waived, but no longer counts toward the verdict. Unused and expired waivers are reported; `--preset` ignores the file's waivers.\n- **`pr-recap` coupling gates need COMPOSABLE.** With the dependency graphs measured (not under `--no-coupling`), `import_cycle` flags a cycle new at head (severity per language in `[pr_recap.import_cycle]`, strictest file wins; Python warns under recommended), `fan_in_growth` flags a file failing SIMPLE that gained dependents past `[pr_recap.fan_in_growth]`, and `blast_radius` notes how many files depend on the change. They cover every changed file regardless of `--max-files`; `--json` findings list the paths behind them in `related`.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.16:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.16\",\n \"publishedAt\": 1791633577827\n}\n\nArchive v1.0.15: 3 files, 6824 bytes\n\nFiles: skill-card.md (2023b), SKILL.md (12517b), _meta.json (125b)\n\nFile v1.0.15:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.8.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority --pr-preset ` | View or persist project priority, preference, and PR gate settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos pr-recap [] [--strict] [--preset ] [--verbose] [--info] [--json]` | Judge a PR or git range against the `[pr_recap]` gates: READY / NEEDS ATTENTION / BLOCKED, exit 1 on BLOCKED (and on NEEDS ATTENTION under `fail_on = \"warn\"`); `--json` emits `topos.pr_recap.v3` |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`) β€” never affects the medal |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **Moving code is not a regression in `pr-recap`.** A pillar lost only because code moved into a file is reported under the `moved_pillar` gate (info by default, warn under strict), naming the source file; a moved function that grew on the way is still `pillar_lost`. Set aside a known finding with a `[[pr_recap.waive]]` entry (`gate`, `path` glob, required `reason`, optional `expires = \"YYYY-MM-DD\"`): it stays in the report, marked waived, but no longer counts toward the verdict. Unused and expired waivers are reported; `--preset` ignores the file's waivers.\n- **`pr-recap` coupling gates need COMPOSABLE.** With the dependency graphs measured (not under `--no-coupling`), `import_cycle` flags a cycle new at head (severity per language in `[pr_recap.import_cycle]`, strictest file wins; Python warns under recommended), `fan_in_growth` flags a file failing SIMPLE that gained dependents past `[pr_recap.fan_in_growth]`, and `blast_radius` notes how many files depend on the change. They cover every changed file regardless of `--max-files`; `--json` findings list the paths behind them in `related`.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.15:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.15\",\n \"publishedAt\": 1791555137195\n}\n\nFile v1.0.15:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos for complexity reduction, structural security checks, and refactor verification.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding agents use Topos to assess code structure, identify refactor targets, and compare code quality before and after changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The suggested installation runs a mutable remote shell script.\n\nMitigation: Download and inspect the installer before running it, and check available signatures or hashes.\n\nRisk: Optional MCP registration can change settings across multiple agent harnesses.\n\nMitigation: Register MCP only in the harnesses you use and review the resulting configuration.\n\nRisk: Structural refactor recommendations can change program behavior or be mistaken for a complete security assessment.\n\nMitigation: Run project tests after edits and use dedicated security checks where needed.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub listing](https://clawhub.ai/krv-labs/skills/topos)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, JSON, Shell commands]\n\n**Output Format:** [CLI tables and ranked lists, Markdown reports, or structured MCP responses]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes medal verdicts, pillar scores, and ranked refactor targets; dependency graph generation may write local artifacts.]\n\n## Skill Version(s):\n\n1.0.15 (source: server release metadata; skill frontmatter says 0.8.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.14: 3 files, 6809 bytes\n\nFiles: skill-card.md (1991b), SKILL.md (12517b), _meta.json (125b)\n\nFile v1.0.14:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.7.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority --pr-preset ` | View or persist project priority, preference, and PR gate settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos pr-recap [] [--strict] [--preset ] [--verbose] [--info] [--json]` | Judge a PR or git range against the `[pr_recap]` gates: READY / NEEDS ATTENTION / BLOCKED, exit 1 on BLOCKED (and on NEEDS ATTENTION under `fail_on = \"warn\"`); `--json` emits `topos.pr_recap.v3` |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`) β€” never affects the medal |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **Moving code is not a regression in `pr-recap`.** A pillar lost only because code moved into a file is reported under the `moved_pillar` gate (info by default, warn under strict), naming the source file; a moved function that grew on the way is still `pillar_lost`. Set aside a known finding with a `[[pr_recap.waive]]` entry (`gate`, `path` glob, required `reason`, optional `expires = \"YYYY-MM-DD\"`): it stays in the report, marked waived, but no longer counts toward the verdict. Unused and expired waivers are reported; `--preset` ignores the file's waivers.\n- **`pr-recap` coupling gates need COMPOSABLE.** With the dependency graphs measured (not under `--no-coupling`), `import_cycle` flags a cycle new at head (severity per language in `[pr_recap.import_cycle]`, strictest file wins; Python warns under recommended), `fan_in_growth` flags a file failing SIMPLE that gained dependents past `[pr_recap.fan_in_growth]`, and `blast_radius` notes how many files depend on the change. They cover every changed file regardless of `--max-files`; `--json` findings list the paths behind them in `related`.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.14:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.14\",\n \"publishedAt\": 1790761157269\n}\n\nFile v1.0.14:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos through complexity reduction, structural security checks, and refactor verification.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding agents use Topos to assess local code quality, prioritize structural refactors, and check whether changes improve measured results.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The documented install command runs an unpinned remote shell script.\n\nMitigation: Prefer a versioned or package-manager installation; otherwise inspect the downloaded script, verify its provenance where possible, and avoid elevated privileges.\n\nRisk: Structural scores may not reveal incorrect behavior or all security issues after a refactor.\n\nMitigation: Treat findings as advisory and run the project's usual tests and security checks after proposed changes.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub skill listing](https://clawhub.ai/krv-labs/skills/topos)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown reports, JSON, Shell commands, Guidance]\n\n**Output Format:** [CLI tables and ranked file lists, or structured MCP results]\n\n**Output Parameters:** [Medal verdict, pillar scores, ranked refactor targets, and change assessment status]\n\n**Other Properties Related to Output:** [Results are advisory; dependency graph artifacts may be generated during analysis.]\n\n## Skill Version(s):\n\n1.0.14 (source: ClawHub release metadata; skill documentation states 0.7.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.13: 3 files, 6817 bytes\n\nFiles: skill-card.md (2052b), SKILL.md (12517b), _meta.json (125b)\n\nFile v1.0.13:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.6.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority --pr-preset ` | View or persist project priority, preference, and PR gate settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos pr-recap [] [--strict] [--preset ] [--verbose] [--info] [--json]` | Judge a PR or git range against the `[pr_recap]` gates: READY / NEEDS ATTENTION / BLOCKED, exit 1 on BLOCKED (and on NEEDS ATTENTION under `fail_on = \"warn\"`); `--json` emits `topos.pr_recap.v3` |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`) β€” never affects the medal |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **Moving code is not a regression in `pr-recap`.** A pillar lost only because code moved into a file is reported under the `moved_pillar` gate (info by default, warn under strict), naming the source file; a moved function that grew on the way is still `pillar_lost`. Set aside a known finding with a `[[pr_recap.waive]]` entry (`gate`, `path` glob, required `reason`, optional `expires = \"YYYY-MM-DD\"`): it stays in the report, marked waived, but no longer counts toward the verdict. Unused and expired waivers are reported; `--preset` ignores the file's waivers.\n- **`pr-recap` coupling gates need COMPOSABLE.** With the dependency graphs measured (not under `--no-coupling`), `import_cycle` flags a cycle new at head (severity per language in `[pr_recap.import_cycle]`, strictest file wins; Python warns under recommended), `fan_in_growth` flags a file failing SIMPLE that gained dependents past `[pr_recap.fan_in_growth]`, and `blast_radius` notes how many files depend on the change. They cover every changed file regardless of `--max-files`; `--json` findings list the paths behind them in `related`.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.13:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.13\",\n \"publishedAt\": 1790760574546\n}\n\nFile v1.0.13:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos for complexity reduction, structural security checks, and refactor verification.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding agents use this skill to assess code quality, identify targeted refactors, and check whether edits improve structural scores in local repositories.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The installation command executes a changeable remote script locally.\n\nMitigation: Install only from a trusted publisher; inspect the installer first or use a pinned package when available.\n\nRisk: Broad MCP setup can register the server across all supported agent environments.\n\nMitigation: Configure only the environments you intend to use rather than choosing --all by default.\n\nRisk: Structural scores cannot establish functional correctness or comprehensive security.\n\nMitigation: Review proposed changes and run project tests and dedicated security checks where needed.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent guidance](https://docs.krv.ai/topos/agents.html)\n- [ClawHub skill listing](https://clawhub.ai/krv-labs/skills/topos)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, Code suggestions, Shell commands, Configuration guidance]\n\n**Output Format:** [Text or Markdown with inline commands and ranked refactor guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include quality verdicts, structural findings, and suggested next steps.]\n\n## Skill Version(s):\n\n1.0.13 (source: ClawHub release metadata; skill frontmatter states 0.6.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.12: 3 files, 6266 bytes\n\nFiles: skill-card.md (2335b), SKILL.md (11092b), _meta.json (125b)\n\nFile v1.0.12:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.6.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority ` | View or persist project priority and preference settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`) β€” never affects the medal |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.12:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.12\",\n \"publishedAt\": 1789561287476\n}\n\nFile v1.0.12:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and AI coding agents use this skill to assess local repositories, identify structural code quality issues, verify refactors, and work toward Topos PLATINUM or GOLD quality goals.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The setup flow asks users to execute a remote installer and install global npm tooling.\n\nMitigation: Review the installer source and provenance before running it, and prefer a pinned, checksum-verified Topos release when available.\n\nRisk: The optional MCP setup can register Topos broadly across supported agent harnesses.\n\nMitigation: Register the MCP server only in the specific agent harness where it is needed instead of using broad registration.\n\nRisk: Topos structural scores can guide refactors that still change application behavior.\n\nMitigation: Run the project's tests or linters after edits and treat Topos results as structural guidance rather than functional proof.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub listing](https://clawhub.ai/krv-labs/skills/topos)\n- [Publisher profile](https://clawhub.ai/user/krv-labs)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, JSON, Shell commands, Configuration]\n\n**Output Format:** [CLI tables, ranked file lists, MCP structured payloads, markdown reports, and shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May write .gitnexus graph artifacts when dependency graph generation is used; the skill itself does not modify source files unless an agent acts on its guidance.]\n\n## Skill Version(s):\n\n1.0.12 (source: ClawHub release metadata; artifact frontmatter reports 0.6.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.11: 3 files, 6292 bytes\n\nFiles: skill-card.md (2452b), SKILL.md (11092b), _meta.json (125b)\n\nFile v1.0.11:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.5.1\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority ` | View or persist project priority and preference settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`) β€” never affects the medal |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.11:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.11\",\n \"publishedAt\": 1786462906960\n}\n\nFile v1.0.11:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD quality goals.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and AI coding agents use this skill to assess local repositories, identify structural quality issues, guide refactors, and verify improvements with Topos CLI or MCP workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Setup can execute mutable remote installer code and install an unpinned global package.\n\nMitigation: Review the installer source and package provenance before installing; prefer inspecting the installer, verifying a published checksum or signature, and pinning exact versions.\n\nRisk: Global installation or topos install --all can make persistent changes to agent harness configuration.\n\nMitigation: Avoid global installs or topos install --all unless the configuration changes are understood and acceptable; verify registration status after setup.\n\nRisk: Topos structural results can guide refactors but do not prove functional correctness or complete security coverage.\n\nMitigation: Run project tests, linters, and dedicated security tools after changes; treat SECURE findings as structural signals rather than full assurance.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub listing](https://clawhub.ai/krv-labs/skills/topos)\n- [Krv Labs publisher profile](https://clawhub.ai/user/krv-labs)\n\n## Skill Output:\n\n**Output Type(s):** [analysis, markdown, json, shell commands, guidance]\n\n**Output Format:** [Markdown guidance, CLI output summaries, shell commands, and MCP JSON payloads]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May write .gitnexus graph artifacts when dependency graph generation is used; the skill itself gives guidance and does not modify source files unless the agent applies edits.]\n\n## Skill Version(s):\n\n1.0.11 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.10: 3 files, 6306 bytes\n\nFiles: skill-card.md (2366b), SKILL.md (11322b), _meta.json (125b)\n\nFile v1.0.10:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.5.1\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority ` | View or persist project priority and preference settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos graphify generate\\|orphans` | Advisory orphan / fragile-edge hints (does not affect evaluate) |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`, `graphify`) β€” never affects the medal |\n| `topos_generate_graphify_graph` | Build the Graphify knowledge graph for `topos_refactor(target=\"graphify\")` |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.10:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.10\",\n \"publishedAt\": 1786247824266\n}\n\nFile v1.0.10:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and AI coding agents use Topos to evaluate local repositories, identify structural code-quality issues, verify refactors, and optimize toward PLATINUM or GOLD goals.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Topos analyzes local repository code and can create .gitnexus artifacts during dependency graph generation.\n\nMitigation: Run it only in repositories where local analysis and generated graph artifacts are acceptable; review generated artifacts before committing them.\n\nRisk: The optional MCP installation can modify agent harness configuration.\n\nMitigation: Use the MCP install command only after reviewing the installation path and verify the resulting harness configuration with `topos status`.\n\nRisk: Topos security and refactor scores are advisory structural signals, not proof of functional correctness or complete security coverage.\n\nMitigation: Run project tests, linters, and appropriate security tools before accepting or shipping code changes based on Topos guidance.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub listing](https://clawhub.ai/krv-labs/skills/topos)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, JSON, Shell commands, Configuration]\n\n**Output Format:** [CLI tables, ranked file lists, Markdown guidance, MCP structured payloads, and shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May create .gitnexus graph artifacts when dependency graph generation is used; does not modify source files unless the agent chooses to edit based on the guidance.]\n\n## Skill Version(s):\n\n1.0.10 (source: server release metadata; artifact frontmatter reports 0.5.1)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.9: 3 files, 6350 bytes\n\nFiles: skill-card.md (2377b), SKILL.md (11322b), _meta.json (124b)\n\nFile v1.0.9:SKILL.md\n\n---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.5.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and PLATINUM is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ PLATINUM), pillar scores (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root. MCP derives the project from the tool's absolute file/directory path (`TOPOS_MCP_FILE_ROOT` is only an optional maximum boundary). Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## Lattice (v0.5.0)\n\n- **16 verdicts** on four generators: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE.\n- **Medals:** 4 pillars pass β†’ PLATINUM; 3 β†’ GOLD; 2 β†’ SILVER; 1 β†’ BRONZE; 0 β†’ SLOP.\n- **`IDEAL` requires all four pillars.** The former three-pillar top verdict is now `SIMPLE_COMPOSABLE_SECURE` (GOLD band). CI or agents pinned to `IDEAL` will fail on NAVIGABLE gate misses.\n- **Default ranking:** `SIMPLE ≻ NAVIGABLE ≻ SECURE ≻ COMPOSABLE`. `.topos.toml` and MCP `preferences.ranking` must list all four pillars.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config show \\| set --priority ` | View or persist project priority and preference settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos graphify generate\\|orphans` | Advisory orphan / fragile-edge hints (does not affect evaluate) |\n| `topos install [--all]` | Register the MCP server in agent harnesses (Claude, Cursor, Codex, …) |\n| `topos uninstall [--all]` | Remove Topos-owned MCP entries from harness configs |\n| `topos status` | Show which harnesses are configured |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the project derived from the MCP tool's absolute file/directory path, with store at `/.gitnexus`. `TOPOS_MCP_FILE_ROOT` is an optional maximum boundary, not normal editor setup. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP requires the store under the derived project). Pass `--no-composable` to disable only COMPOSABLE/MDG scoring; SIMPLE, SECURE, and the AST-derived NAVIGABLE pillar continue to be scored. `topos evaluate` accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) β€” `inspect` does not β€” and `topos config set --priority` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`, `graphify`) β€” never affects the medal |\n| `topos_generate_graphify_graph` | Build the Graphify knowledge graph for `topos_refactor(target=\"graphify\")` |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and PLATINUM is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd (or the MCP-derived project). Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo) so only that repo is walked. MCP does not need `TOPOS_MCP_FILE_ROOT` for normal editor use.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **`topos_refactor` (MCP-only) is advisory.** It does not replace `topos evaluate` / `topos_evaluate_file` for scoring. There is no `topos refactor` CLI subcommand.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Any other status β€” `LATERAL_MOVE`, `REGRESSION`, `REGRESSION_SCORE`, `SUSPICIOUS_NO_STRUCTURAL_CHANGE` β€” is not ready.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.9:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.9\",\n \"publishedAt\": 1786207582626\n}\n\nFile v1.0.9:skill-card.md\n\n## Description:\n\nEvaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and AI coding agents use Topos to assess local repositories, identify structural quality issues, guide refactors, and verify whether changes improve SIMPLE, COMPOSABLE, SECURE, and NAVIGABLE scores.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Topos runs local tooling that reads repository files and git state and may create `.gitnexus` analysis artifacts.\n\nMitigation: Install and run it only in repositories where local code analysis and generated analysis artifacts are acceptable.\n\nRisk: `topos install --all` can modify supported agent harness MCP configuration.\n\nMitigation: Review harness configuration before and after installation, and use CLI-only workflows when MCP registration is not desired.\n\nRisk: Refactor guidance can improve structural scores without proving functional correctness.\n\nMitigation: Review proposed edits and run the project's normal tests, linters, or type checks before committing changes.\n\nRisk: SECURE scoring is a structural signal rather than complete security assurance.\n\nMitigation: Use dedicated security review or SAST tooling for high-stakes code and treat SECURE findings as advisory.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub listing](https://clawhub.ai/krv-labs/skills/topos)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance, CLI output, and MCP structured JSON payloads]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce ranked refactor targets, medal verdicts, pillar scores, and local .gitnexus analysis artifacts.]\n\n## Skill Version(s):\n\n1.0.9 (source: release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.8: 3 files, 5945 bytes\n\nFiles: skill-card.md (2681b), SKILL.md (9870b), _meta.json (124b)\n\nFile v1.0.8:SKILL.md\n\n---\nname: topos\ndescription: Structural code quality metrics, lattice verification, and refactor loops for agent-written code.\nversion: \"0.4.4\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on three pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE** β€” and maps results to a medal lattice (SLOP β†’ GOLD). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward GOLD or SILVER medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward GOLD/SILVER medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / GOLD scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for baseline comparisons (`topos assess_worktree_change`, untracked baselines via snapshot flow)\n- `.gitnexus` dependency graph for COMPOSABLE / GOLD scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and GOLD is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ GOLD), pillar scores (SIMPLE, COMPOSABLE, SECURE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default. Pass `--gitnexus-dir` / `gitnexus_dir` to select a store; its parent becomes the COMPOSABLE project root (so you can evaluate from `$HOME` against `~/repo/.gitnexus`).\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config` | View or edit project priority and preference settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos graphify generate\\|orphans` | Advisory orphan / fragile-edge hints (does not affect evaluate) |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nWithout `--gitnexus-dir`, COMPOSABLE uses process **cwd** (CLI) or the MCP **file root** (`TOPOS_MCP_FILE_ROOT`, else server cwd), with store at `/.gitnexus`. With `--gitnexus-dir` / `gitnexus_dir`, the store's parent is the COMPOSABLE project root for freshness and `gitnexus analyze` (CLI allows absolute paths outside cwd; MCP still requires the store under the file root). Pass `--no-composable` to score SIMPLE/SECURE only. The CLI accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) and `topos config` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`, `graphify`) β€” never affects the medal |\n| `topos_generate_graphify_graph` | Build the Graphify knowledge graph for `topos_refactor(target=\"graphify\")` |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and GOLD is unreachable β€” check `warnings`.\n- **Missing `--gitnexus-dir` from a parent directory β†’ slow COMPOSABLE setup.** Without the override, freshness fingerprints CLI cwd / MCP file root. Prefer `--gitnexus-dir /.gitnexus` (or `cd` into the repo / set `TOPOS_MCP_FILE_ROOT`) so only that repo is walked.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **`topos refactor` is advisory.** It does not replace `topos evaluate` for scoring.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Status is not `SUSPICIOUS_NO_STRUCTURAL_CHANGE` or `REGRESSION`.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.8:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.8\",\n \"publishedAt\": 1785886946995\n}\n\nFile v1.0.8:skill-card.md\n\n## Description:\n\nStructural code quality metrics, lattice verification, and refactor loops for agent-written code.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[krv-labs](https://clawhub.ai/user/krv-labs)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and AI coding agents use Topos to assess local repositories for structural code quality, identify refactor targets, and verify whether changes improve SIMPLE, COMPOSABLE, and SECURE scores.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Setup can run a remote installer and install npm package code locally.\n\nMitigation: Review the install script and npm package source before installation, especially in managed or production environments.\n\nRisk: Optional MCP setup can register local tools in supported agent harnesses.\n\nMitigation: Run the documented status command after setup and keep MCP registration limited to intended environments.\n\nRisk: Topos inspects local repositories and can create .gitnexus graph artifacts.\n\nMitigation: Run it only on repositories the user intends to analyze and account for generated .gitnexus artifacts in workspace hygiene.\n\nRisk: Structural refactor guidance may change software behavior even when quality scores improve.\n\nMitigation: Run project tests, linters, and review after each edit; treat Topos results as structural signals rather than proof of functional correctness.\n\nRisk: SECURE medal findings are structural heuristics, not full security assurance.\n\nMitigation: Pair Topos with dedicated security tooling for high-stakes code and explicitly review any remaining SECURE findings.\n\n## Reference(s):\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)\n- [ClawHub skill listing](https://clawhub.ai/krv-labs/skills/topos)\n- [Publisher profile](https://clawhub.ai/user/krv-labs)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, JSON, Shell commands, Guidance]\n\n**Output Format:** [CLI tables, ranked file lists, Markdown guidance, and MCP structured JSON payloads]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May write local .gitnexus graph artifacts when dependency graph generation is requested; does not require external credentials.]\n\n## Skill Version(s):\n\n1.0.8 (source: server release metadata; artifact frontmatter reports 0.4.4)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.7: 3 files, 5862 bytes\n\nFiles: skill-card.md (2423b), SKILL.md (9942b), _meta.json (124b)\n\nFile v1.0.7:SKILL.md\n\n---\nname: topos\ndescription: Structural code quality metrics, lattice verification, and refactor loops for agent-written code.\nversion: \"0.4.3\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on three pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE** β€” and maps results to a medal lattice (SLOP β†’ GOLD). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward GOLD or SILVER medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward GOLD/SILVER medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / GOLD scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for baseline comparisons (`topos assess_worktree_change`, untracked baselines via snapshot flow)\n- `.gitnexus` dependency graph for COMPOSABLE / GOLD scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\nclaude mcp add --transport stdio topos -- topos mcp\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated security tooling for high-stakes code; acknowledge remaining SECURE findings explicitly.\n\nRisk: Without GitNexus installed, COMPOSABLE scores are unavailable and GOLD is unreachable.\n\nMitigation: Install `gitnexus` (`npm install -g gitnexus`); check MCP `warnings` and `coupling_available` before trusting composability scores.\n\nRisk: Cosmetic edits (whitespace, rename-only) may appear as improvements but do not move the lattice.\n\nMitigation: Stop when MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`; require `IMPROVEMENT` or `IMPROVEMENT_SCORE` before accepting a change.\n\n## Skill Output\n\n**Output type(s):** Analysis, markdown reports, JSON (MCP), shell commands\n\n**Output format:** CLI tables and ranked file lists; MCP structured payloads with `agent_contract` fields; per-function inspect detail\n\n**Output parameters:** Medal verdict (SLOP β†’ GOLD), pillar scores (SIMPLE, COMPOSABLE, SECURE), ranked refactor targets, assessment status (`IMPROVEMENT`, `REGRESSION`, etc.)\n\n**Other properties:** Writes `.gitnexus` graph artifacts when depgraph is generated; does not modify source files unless the agent chooses to edit based on guidance\n\n## References\n\n- [Topos documentation](https://docs.krv.ai/topos/)\n- [Agent contract](https://docs.krv.ai/topos/agents.html)\n- [Source repository](https://github.com/Krv-Labs/topos)\n- [ClawHub listing](https://clawhub.ai/Krv-Labs/topos)\n\n## Agent Loop\n\n1. **Measure** β€” `topos evaluate -r` (CLI) or `topos_evaluate_file` / `topos_evaluate_project` (MCP). COMPOSABLE is included by default; run the CLI from the repo root (MCP: set file root to that repo). Pass `gitnexus_dir` only to select a non-default store under that root.\n2. **Inspect** β€” `topos inspect ` or `topos_inspect_code` for per-function complexity and metric detail.\n3. **Edit** β€” one focused structural change (extract helper, simplify branch, decouple import).\n4. **Verify** β€” re-run evaluate, or use `topos_assess_worktree_change` (baseline `HEAD`) for MCP loops. For untracked baselines: `topos_begin_refactor` β†’ edit β†’ `topos_assess_snapshot`.\n5. **Behavior check** β€” run project tests or linters; Topos does not prove correctness.\n\nStop when the target medal is reached, the priority pillar passes, or further iterations plateau. Prefer structured `agent_contract` fields over parsing prose.\n\n## CLI Reference\n\n| Command | Purpose |\n| --- | --- |\n| `topos evaluate -r` | Show the cumulative project quality rollup |\n| `topos evaluate -r --failures ` | List the files whose gates fail one pillar |\n| `topos evaluate -r --info` | Select a weak file and show ranked line-level refactor targets |\n| `topos config` | View or edit project priority and preference settings |\n| `topos inspect ` | Deep per-file metrics and suggestions |\n| `topos compare ` | AST edit distance between two versions |\n| `topos coverage ... --tests ... [-r]` | Structural test coverage (UAST + k-gram recall) |\n| `topos depgraph generate` | Build GitNexus graph for COMPOSABLE scoring |\n| `topos graphify generate\\|orphans` | Advisory orphan / fragile-edge hints (does not affect evaluate) |\n| `topos mcp` | Start the MCP server for tool-based agent loops |\n\nRun CLI `evaluate` / `inspect` / `depgraph` from the **repo root that owns `.gitnexus`**. COMPOSABLE freshness and `gitnexus analyze` always use process **cwd** as the project root; `--gitnexus-dir` only selects a store path under that cwd (default `/.gitnexus`) β€” it does not retarget the root. Pass `--no-composable` to score SIMPLE/SECURE only. The CLI accepts a one-run `--priority` override (a single pillar or a full comma-separated ranking) and `topos config` persists project defaults; MCP additionally returns the induced preference walk. Advisory `cycles`/`dependencies`/`process` hints are MCP-only, via `topos_refactor`.\n\nFor MCP, the same rule uses the server **file root** (`TOPOS_MCP_FILE_ROOT`, else server cwd): set the file root to the repo, and use `gitnexus_dir` only for a non-default store under that root.\n\n## MCP Tool Reference\n\n| Tool | Purpose |\n| --- | --- |\n| `topos_get_doc(topic=\"agent-contract\")` | Compact loop contract β€” read first |\n| `topos_evaluate_file` | Score one file; returns 3 ranked edit spans (`refactor_targets`, gate failures first) |\n| `topos_evaluate_project` | Project rollup and worst-file list |\n| `topos_inspect_code` | Deep per-function complexity and metrics |\n| `topos_assess_worktree_change` | Compare working tree to a git baseline |\n| `topos_begin_refactor` / `topos_assess_snapshot` | Snapshot flow for untracked baselines |\n| `topos_assess_improvement` | Side-by-side variant comparison |\n| `topos_assess_changeset` | Assess several edited files at once against a git baseline |\n| `topos_generate_depgraph` / `topos_depgraph_status` | Force-refresh, or read-only diagnose, the GitNexus graph |\n| `topos_calculate_coverage` | Structural test coverage (separate from lattice) |\n| `topos_evaluate_code` | Score a source string when there is no file on disk |\n| `topos_inspect_code` / `topos_compare_code` / `topos_compare_files` | Deep metrics; AST edit distance between two versions |\n| `topos_preference_walk` | Resolve target / fallback / next-step verdicts for a ranking |\n| `topos_refactor` | Advisory hotspots (`cycles`, `dependencies`, `process`, `graphify`) β€” never affects the medal |\n| `topos_generate_graphify_graph` | Build the Graphify knowledge graph for `topos_refactor(target=\"graphify\")` |\n\nMCP tool arguments are **flat objects** β€” `{\"filepath\": \"...\"}`, not `{\"params\": {...}}`.\n\n## Pitfalls\n\n- **No GitNexus β†’ no COMPOSABLE.** The graph is generated automatically, but only if `gitnexus` is installed. If it isn't, `coupling_available` is `false` and GOLD is unreachable β€” check `warnings`.\n- **Wrong cwd / file root β†’ slow or hung COMPOSABLE setup.** Freshness fingerprints the whole project root (CLI cwd / MCP file root). Running from `$HOME` with `--gitnexus-dir ~/…/repo/.gitnexus` still walks home and can appear stuck on β€œindexing”; `cd` into the repo (or point MCP `TOPOS_MCP_FILE_ROOT` at it) instead.\n- **Cosmetic edits don't count.** Whitespace and rename-only changes won't move the lattice; MCP returns `SUSPICIOUS_NO_STRUCTURAL_CHANGE`.\n- **SECURE is structural, not full SAST.** Pair with dedicated security tooling for high-stakes code.\n- **`topos refactor` is advisory.** It does not replace `topos evaluate` for scoring.\n\n## Verification\n\nA change is ready when:\n\n- Assessment status is `IMPROVEMENT` or `IMPROVEMENT_SCORE` (MCP), or the evaluate verdict improved (CLI).\n- Status is not `SUSPICIOUS_NO_STRUCTURAL_CHANGE` or `REGRESSION`.\n- Active SECURE findings are fixed or explicitly acknowledged.\n- Relevant tests/type checks pass, or their absence is reported.\n\n## Ethical Considerations\n\nUsers should review agent-proposed code changes before committing, especially when refactoring production systems. Topos is an advisory structural quality tool; organizations should apply their own security, compliance, and code-review policies before deployment.\n\nFile v1.0.7:_meta.json\n\n{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.7\",\n \"publishedAt\": 1785274447798\n}\n\nFile v1.0.7:skill-card.md\n\n## Description:
\nStructural code quality metrics, lattice verification, and refactor loops for agent-written code.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[krv-labs](https://clawhub.ai/user/krv-labs)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and AI coding agents use Topos to measure structural quality in local repositories, identify refactor targets, and verify whether changes improve SIMPLE, COMPOSABLE, and SECURE scores.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The installer and global npm package execute code on the local machine.
\nMitigation: Review the remote installer and global package before installation.
\nRisk: Refactor guidance can change program behavior because Topos measures structure, not functional correctness.
\nMitigation: Review changes and run the project's tests or linters before accepting refactors.
\nRisk: SECURE scores are structural heuristics rather than full security assurance.
\nMitigation: Use dedicated security tooling for high-stakes code and explicitly review remaining SECURE findings.
\nRisk: Dependency graph generation may create local .gitnexus artifacts.
\nMitigation: Review generated artifacts and repository status before committing changes.
\n\n\n## Reference(s):
\n- [Topos documentation](https://docs.krv.ai/topos/)
\n- [Topos agent contract](https://docs.krv.ai/topos/agents.html)
\n- [ClawHub listing](https://clawhub.ai/krv-labs/skills/topos)
\n\n\n## Skill Output:
\n**Output Type(s):** [analysis, markdown, JSON, shell commands, guidance]
\n**Output Format:** [CLI tables and ranked file lists, Markdown guidance, and MCP structured JSON payloads.]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May write local .gitnexus graph artifacts when dependency graph generation is enabled; does not modify source files unless the agent acts on the guidance.]
\n\n## Skill Version(s):
\n1.0.7 (source: ClawHub release metadata; artifact frontmatter reports 0.4.3)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
","readmeExcerpt":"Skill: topos Owner: krv-labs Summary: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals. Tags: latest:1.0.16 Version history: v1.0.16 | 2026-10-10T11:59:37.827Z | auto - Bumped version to 0.9.0. - Removed the file skill-card.md. - Updated SKILL.md content for accuracy and alignment with current functionality. - No breaking changes to us","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"curl -fsSL https://docs.krv.ai/topos/install.sh | bash"},{"language":"bash","snippet":"curl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring"},{"language":"bash","snippet":"topos install --all # registers the MCP server in every supported harness\ntopos status # verify registration"},{"language":"bash","snippet":"curl -fsSL https://docs.krv.ai/topos/install.sh | bash"},{"language":"bash","snippet":"curl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring"},{"language":"bash","snippet":"topos install --all # registers the MCP server in every supported harness\ntopos status # verify registration"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: topos\ndescription: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals.\nversion: \"0.9.0\"\nhomepage: https://docs.krv.ai/topos/\nmetadata:\n openclaw:\n requires:\n bins: [topos]\n homepage: https://docs.krv.ai/topos/\n os: [macos, linux]\n emoji: \"πŸ“\"\n hermes:\n tags: [code-quality, refactoring, security, metrics]\n category: software-development\n requires_toolsets: [terminal]\n---\n\n# Topos\n\nTopos scores code on four pillars β€” **SIMPLE**, **COMPOSABLE**, **SECURE**, **NAVIGABLE** β€” and maps results to a medal lattice (SLOP β†’ PLATINUM). Use it in a closed loop: measure, edit, re-measure.\n\n## Use Case\n\nDevelopers and AI coding agents use this skill to improve structural code quality, reduce complexity, verify refactors, and optimize toward PLATINUM or GOLD medals. It supports both CLI and MCP agent loops on local repositories.\n\n**Deployment geography:** Global (local execution; no region-restricted services).\n\n## When to Use\n\nLoad this skill when the user asks to improve code quality, reduce complexity, check structural security footguns, verify a refactor, or optimize toward PLATINUM/GOLD medals.\n\n## Requirements / Dependencies\n\n**Requires API Key or External Credential:** No\n\n**Credential Type(s):** None\n\n**Runtime dependencies:**\n\n```bash\ncurl -fsSL https://docs.krv.ai/topos/install.sh | bash\nnpm install -g gitnexus # enables COMPOSABLE / PLATINUM scoring\n```\n\n- `topos` CLI on `PATH` (install via [docs.krv.ai/topos/install.sh](https://docs.krv.ai/topos/install.sh))\n- Git repository for MCP baseline comparisons (`topos_assess_worktree_change`; untracked baselines via `topos_begin_refactor` β†’ `topos_assess_snapshot`)\n- `.gitnexus` dependency graph for COMPOSABLE / PLATINUM scoring (generated automatically when `gitnexus` is installed; force refresh with `topos depgraph generate` or `topos_generate_depgraph`)\n\nCOMPOSABLE is scored by default: `evaluate` / `inspect` and the MCP evaluate\ntools detect a missing or stale `.gitnexus` and regenerate it before scoring.\nRun `topos depgraph generate` only to force a refresh.\n\n**Optional MCP setup** (for tool-based agents, not required for CLI-only use):\n\n```bash\ntopos install --all # registers the MCP server in every supported harness\ntopos status # verify registration\n```\n\nDo not include secrets in prompts, logs, or output. Topos reads local source files and git state only; it does not transmit code to external services.\n\n## Known Risks and Mitigations\n\nRisk: The skill may guide agents to apply structural refactors that change behavior; Topos measures structure, not functional correctness.\n\nMitigation: Run project tests or linters after each edit; treat Topos verdicts as structural signals, not proof of correctness.\n\nRisk: Agents may trust SECURE medal findings as full security assurance; Topos SECURE checks are structural heuristics, not full SAST.\n\nMitigation: Pair with dedicated securi"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn791q4c49jmw6xqwkwe3x1m6x8az9e7\",\n \"slug\": \"topos\",\n \"version\": \"1.0.16\",\n \"publishedAt\": 1791633577827\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals. Skill: topos Owner: krv-labs Summary: Evaluate and improve code with Topos. Use for complexity reduction, security checks, refactor verification, and PLATINUM/GOLD goals. Tags: latest:1.0.16 Version history: v1.0.16 | 2026-10-10T11:59:37.827Z | auto - Bumped version to 0.9.0. - Removed the file skill-card.md. - Updated SKILL.md content for accuracy and alignment with current functionality. - No breaking changes to us","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1066,"uniquenessScore":49,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T12:21:57.674Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T12:21:57.674Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:45:02.782Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation β€’ (~400 MCP servers for AI agents) β€’ AI Automation / AI Agent with MCPs β€’ AI Workflows & AI Agents β€’ MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}