[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_111":112},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":21,"_24":25,"_26":27,"_28":29,"_30":31,"_32":33,"_34":25,"_35":36,"_37":-5,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":-5,"_55":47,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":-5,"_76":-5,"_77":47,"_78":-5,"_79":80,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92},"apiUrl","https://odel.app/api","creator","hslee16","moduleId","archy","@hslee16/archy","displayName","tagline","Architectural sensor for Python codebases.","iconKey","https://avatars.githubusercontent.com/u/3871876?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783339913000,"updatedAt",1788669613000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hslee16%2Farchy","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",7,"upstreamUpdatedAt",1788659717000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/hslee16/Archy","githubRepoFullName","hslee16/Archy","releaseId","ext-hslee16-archy","version","0.46.2","descriptionMarkdown","\n\n

$\"archy\"$

\n\n[![PyPI](https://img.shields.io/pypi/v/archy.svg)](https://pypi.org/project/archy/)\n[![Python](https://img.shields.io/pypi/pyversions/archy.svg)](https://pypi.org/project/archy/)\n[![CI](https://github.com/hslee16/archy/actions/workflows/ci.yml/badge.svg)](https://github.com/hslee16/archy/actions/workflows/ci.yml)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![License](https://img.shields.io/pypi/l/archy.svg)](LICENSE)\n[![Glama](https://glama.ai/mcp/servers/hslee16/archy/badges/score.svg)](https://glama.ai/mcp/servers/hslee16/archy)\n\n> **Your folders show your architecture. Your imports decide it.**\n> archy turns a Python import graph into something an agent can *use*: blast radius before an edit, the tests that edit affects, the modules most at risk. And it *fails* when the graph disagrees with the layers you declared. Same graph either way, as a CLI and an MCP server, every session and in CI.\n\n> [!IMPORTANT]\n> **Status, 2026-09-02: active again, on one question.**\n>\n> archy is back in development after five weeks in maintenance. The focus is\n> narrow and it is not the original one: **coding agents running a small model\n> on local hardware.** A DGX Spark carries 128 GB of unified memory, which puts\n> roughly 70B to 200B models within local reach at 4-bit, but their usable\n> context stays far below a frontier API model's and degrades faster across it.\n> Under that constraint a structural answer to \"what does this change reach,\n> and what breaks if it is wrong\" may substitute for context the model cannot\n> hold at all.\n>\n> **This is a bet, not a finding, and the difference matters here.** Everything\n> in the section below still stands: I measured this tool's premise four times\n> and the problem it prevents is rare, the one real effect was capped at 12% by\n> how seldom the mistake happens, and two token-reduction propositions came back\n> null. **Every one of those studies ran against an agent with a large context\n> window and strong long-range code reasoning** - the population where a\n> structural index has the least to add, because the model can often just read\n> the code. A small local model is a different population. That is the one\n> reading of the prior nulls that does not require reinterpreting them, and it\n> might still be wrong.\n>\n> So the discipline does not relax because the project is active again. The\n> thresholds are pre-registered in\n> [#408](https://github.com/hslee16/archy/issues/408), **no treatment arm has\n> been scored**, and any result, including another null, gets published in\n> [`docs/WHAT_DIDNT_WORK.md`](https://github.com/hslee16/Archy/blob/main/docs/WHAT_DIDNT_WORK.md) like the other four.\n> Nothing archy ships today claims a local-model benefit; `archy brief` (v0.46)\n> shipped explicitly on judgment ahead of that measurement rather than on one.\n>\n> **What is not changing.** The original use case is still supported and still\n> works: layer governance in CI, blast radius and affected-tests for a frontier\n> agent, the MCP server. This is an adjacent focus, not a replacement, and\n> nothing is being removed or renamed to make room for it. Bugs still get fixed,\n> pull requests still get reviewed, and the `good first issue` tickets are still\n> deliberately left open.\n\n## Read this first: I measured the premise, and it was wrong\n\nI built archy after watching coding agents produce changes that passed review and rotted the import graph underneath. Then I measured whether that happens, and **it barely does.**\n\n| measurement | subject | rate |\n|---|---|---|\n| 25 live agent runs on the riskiest SWE-bench tasks | cycles or declared-layer violations | **0%** (95% upper bound 12%) |\n| 1,072 human commits, 11 repos | cycles introduced | **0.5%** per commit |\n| 151 commit pairs in projects that declare an architecture | contract violations | **0.66%** per commit |\n| 107 samples of those same projects over time | rules going stale, coverage eroding | **null on all four pre-registered signals** |\n| 25 agents each building a backend to a specified architecture | wrong dependency direction | **12%**, and a checker in the loop took it to 0% |\n\nSo: the problem is real (I have watched a developer's own architecture rule get broken in the wild), and it is **rare, for agents and humans alike**. \"Agents will rot your import graph\" is a claim I made and have retracted. Nobody has measured what one occurrence costs, so I cannot argue \"rare but expensive\" either.\n\n**The last row is the one that says what archy is for.** All 25 unaided agents produced the four layer directories correctly. Every failure was an import going the wrong way: entities reaching down into data access. They got the *layout* right and the *direction* wrong, and a directional rule caught all three cases at no cost to the API's behaviour.\n\nThat is the shape of the whole thing. **Layout is visible in a file tree. Direction, transitive reach and cycles are visible nowhere**, at any zoom level, in any single file. And a separate study found that once one of these lands it is *never repaired*: zero violations were resolved across the sampled corpus, and 2 of 14 repositories sat on broken contracts indefinitely. Rare and permanent, not rare and self-healing.\n\n**What that means for the roadmap: it is closed.** Feature work premised on \"agents will wreck your architecture\" went off the table when that premise was retracted. What survives is narrower and now has a number behind it: directional rules, transitive contracts and cycle detection, checked every session. That is a real job and archy does it, but four studies produced no evidence that *more* of it is worth building, and the honest reading of four headroom-limited results is that the next feature is not the missing piece.\n\nSo archy is finished rather than abandoned. It is maintained, bugs get fixed, and contributions are welcome. There is no roadmap left to publish.\n\nThe full write-up, including the six measurement artifacts that nearly turned a failed study into a success story, is in [`docs/WHAT_DIDNT_WORK.md`](https://github.com/hslee16/Archy/blob/main/docs/WHAT_DIDNT_WORK.md). If you only read one thing here, read that.\n\n## The failure it catches\n\n![archy's layer contract: four stacked layers, cli over policy over graph over parser, with dependencies allowed only downward and one forbidden upward edge from the graph layer into cli marked as the violation.](https://raw.githubusercontent.com/hslee16/Archy/main/docs/assets/diagrams/layer-contract.png)\n\nNothing in that picture is derived. Which layer a module belongs to, and which direction is forbidden, are facts you write down in `archy.yaml`; archy only checks that the source still agrees with them.\n\nHere is the failure it was built for, compressed into one line. This is archy's own source, under archy's own layer rules, with a single import of the kind an agent adds when it needs a helper and the nearest one is upward:\n\n```python\n# src/archy/graph.py\nfrom archy.cli import main # convenience import. The diff looks harmless.\n```\n\n```console\n$ uvx archy check .\n# 1 layer violation(s) (config: archy.yaml)\n\ngraph -> cli (forbidden):\n archy.graph -> archy.cli (line: 21)\n\n$ echo $?\n1\n\n$ uvx archy cycles .\n# 1 cycle(s) found\n\nCycle of 8 module(s):\n - archy.cli\n - archy.conventions\n - archy.duplicates\n - archy.graph\n - archy.index\n - archy.mcp\n - archy.simulate\n - archy.watcher\n\n$ uvx archy score .\n# archy score: 0.647 (0.656 before the edit)\n...\nacyclicity: 0.942 (1 cycles, tangle=0.058)\n# graph: 139 modules, 264 edges (263 before the edit)\n```\n\nOne import, one edge. A forbidden layer edge, an eight-module cycle, and the score down 0.009. Nothing in the diff itself says any of that, and no amount of reading the file reveals it, because the rule that makes it a violation is not in the source. You supplied it.\n\nNote the size of the score move. 0.009 is small, and that is the honest shape of this problem: no single edit looks alarming on the number. The cycle count going 0 to 1 and `check` exiting 1 are the signals that matter here, and the score is what catches the version of this that happens forty times over six weeks. Read [`docs/SCORING.md`](https://github.com/hslee16/Archy/blob/main/docs/SCORING.md) before treating the composite as a quality gate.\n\nThat example is a *direct* forbidden import, which is the easy case: an agent that reads `archy.yaml` first can catch it without archy. The harder and more honest case is a **transitive** violation, where the edit adds no forbidden import at all and reading the config tells you nothing. [`docs/WALKTHROUGH.md`](https://github.com/hslee16/Archy/blob/main/docs/WALKTHROUGH.md) is a one-command reproduction of that, and it states plainly which archy surfaces catch it (one) and which miss it (three).\n\nReproduce the example above on a checkout: add that import to `src/archy/graph.py`, then run the three commands **with the `uvx` prefix**. It has to be a separate archy, because that one import is a genuine runtime import cycle, and an editable-installed archy can no longer start to report on itself. `archy check` exits 1, which is what it does in CI and what the MCP server reports to an agent before it commits.\n\n![archy demo](https://raw.githubusercontent.com/hslee16/Archy/main/docs/demo.gif)\n\n**What archy is not:** a code-navigation tool. It will not help an agent find and read code faster; that job belongs to symbol-level, multi-language graph tools like [codegraph](https://github.com/colbymchenry/codegraph), and they are better at it. archy answers the other question: *you declared this codebase should have these layers, no cycles, and this score; is the agent's edit about to break that, and has the trend been sliding for six weeks?* Nothing in a navigation graph carries that intent, because intent is not in the source, you supply it.\n\nThe sharp version, re-checked against codegraph on 2026-07-27: it ships no cycle detection, no config in which to declare layers or forbidden edges, and no command that exits non-zero on a violation. It will happily *show* you that `models` imports `repositories` if you ask the right question. It cannot tell you that is wrong, because wrongness needs a declaration and there is nowhere to put one. **Descriptive tools answer questions; archy makes an assertion that breaks the build.** The two are both local MCP servers and compose fine; run them together. See [`docs/research/CODEGRAPH_COMPETITIVE_ANALYSIS.md`](https://github.com/hslee16/Archy/blob/main/docs/research/CODEGRAPH_COMPETITIVE_ANALYSIS.md) for the full comparison, including where archy loses and why this distinction is a choice they made rather than a wall they hit.\n\n## Start in one command\n\n```bash\nuvx archy install # detects Claude Code, Cursor, Codex, opencode, Continue and wires each one up\n```\n\nNothing lands on your PATH: the config it writes runs `uvx archy mcp` on demand. Prefer a real install? `pip install archy`, `uv tool install archy`, or `pipx install archy`. Either way, try it on a project without installing anything:\n\n```bash\nuvx archy score . # one-shot architectural health number\nuvx archy cycles . # import cycles, Tarjan SCCs plus self-loops\nuvx archy check . # layer rules from archy.yaml; exits 1 on violation\n```\n\n**Free, MIT licensed, no commercial version planned.** One maintainer, Python only. Built by [Alex Lee](https://github.com/hslee16/Archy).\n\n**Status:** v0.46.2, working, installed and maintained; in active development on the local-model line (see the top of this page). Usable today via:\n\n| Mode | Command |\n|---|---|\n| Inspection | `archy graph`, `archy cycles` |\n| CI governance | `archy check` (reads `archy.yaml`; `--contracts` nests the transitive import-linter verdict in the same output, reported, never gated) |\n| Transitive contracts | `archy contracts` (reads `.importlinter` (canonical) or falls back to `archy.yaml`; requires `archy[contracts]`) |\n| One-shot score | `archy score` |\n| Trended score | `archy score --record` + `archy trend` |\n| Refactor priority | `archy hotspots` (CC x git churn), `archy what-to-refactor-next` (fused hotspots + edit-risk) |\n| Duplicate detection | `archy duplicates` (two-tier: likely duplicates vs demoted variants - same-class/boilerplate/test/vendored; advisory, not a score axis) |\n| House style | `archy conventions` (naming families by home module, kind families by transitive base, `NAME = Ctor(...)` registries, mirrored surfaces, a gate inventory kept separate from user-error exits, model census, and the members a project's own `__all__` or docs leave out - derived from the source, so an agent stops guessing conventions; advisory, exits 0 on a successful report, and `--module NAME` switches to a complete, unranked lookup on one module - what it imports, what imports it, and whether it was set aside - which answers a negative the ranked report cannot; `--emit-headers` derives a per-module block (what it owns, what mirrors it, whether a finding here gates) from that same report and prints it, `--write` puts it in the module docstring, and `--check` exits 1 when one is stale) |\n| Change coupling | `archy coupling` (module pairs that co-change in git history but share no import/call edge - hidden dependencies; source-only, advisory) |\n| CI impact lookup | `archy affected` (`git diff` -> impacted modules + tests, depth-capped) |\n| Human-facing export | `archy render --view dsm\\|trend` (one self-contained HTML file: no JS, no CDN, offline, byte-stable) |\n| Pre-task briefing | `archy brief` (one screen composing conventions, layer coverage and the gate inventory for an agent to read BEFORE it starts, plus optional `--contracts`; advisory, always exits 0) |\n| MCP server | `archy mcp` (cached: warm graph builds in seconds even on 10k+ module repos) |\n| Parse cache | `archy index sync` / `archy index clear` (persistent `.archy/index.db`; transparent under the MCP server) |\n| Agent install | `archy install` / `archy uninstall` (auto-detect Claude Code, Cursor, Codex, opencode, Continue; wire in or cleanly remove the MCP server) |\n\nHow the score is computed and how to read it: [`docs/SCORING.md`](https://github.com/hslee16/Archy/blob/main/docs/SCORING.md). Benchmarks against pydantic, fastapi, flask, pytest, and archy-on-archy: [`docs/CASE_STUDIES.md`](https://github.com/hslee16/Archy/blob/main/docs/CASE_STUDIES.md). Design rationale and comparison with sentrux: [`docs/LEARNINGS.md`](https://github.com/hslee16/Archy/blob/main/docs/LEARNINGS.md).\n\n## In the wild\n\n[`ADOPTERS.md`](https://github.com/hslee16/Archy/blob/main/ADOPTERS.md) is empty and no issue has yet been filed by anyone but me. Outside **pull requests** are a different story and recent: three landed on 2026-07-25, two merged. Good-first tickets are labelled and deliberately left for others.\n\nIf you are running archy on a real codebase I would like to hear what it found, especially if the answer is \"nothing useful\" - that answer is now supported by measurement rather than merely possible.\n\n## Why\n\nThe failure at the top of this page is the whole reason archy exists: I wanted a single number per commit that would have caught it.\n\nAI agents generate code at machine speed, and the reasoning went: without a feedback loop on *structural* health (module coupling, import cycles, layer violations), codebases drift architecturally even when every individual change looks fine in review.\n\n**That reasoning is the part I tested and could not support.** Twenty-five agent runs produced zero structural regressions, and human commits break their own declared rules on 0.66% of commits. The drift may still be real over long horizons, which is not what a per-edit measurement can see, but I have no evidence for it and I am not going to assert it. The rest of this section is the case as I originally made it, kept because the citations are accurate even where my inference from them was not.\n\n**Where a feedback loop did pay is narrower, and it is the moment code is written rather than the patrol afterwards.** Building a new backend to a specified architecture, 3 of 25 unaided agents got the dependency direction wrong; with a checker in the loop, none did, and the API behaved just as well. That is one model, one framework, and the mildest of the Constraint Decay paper's conditions, so it is not a general claim. It does say the loop is worth having at generation time, where the mistake is cheap to prevent and, per the decay study, never repaired afterwards.\n\n![archy's architecture: your Python source is parsed into an import graph, which feeds both the analysis modules and the layer policy you declare in archy.yaml, with every result reaching you through one shared set of surfaces.](https://raw.githubusercontent.com/hslee16/Archy/main/docs/assets/diagrams/architecture.png)\n\nWhat that buys you is placement: it runs in CI, in pre-commit, and as an MCP server (`archy mcp`), so a coding agent can read its own architectural impact before it commits rather than after review.\n\nThe agent-feedback framing is empirically supported by 2025-2026 research: the Navigation Paradox paper shows large LLM context windows do not eliminate the need for structural graph navigation, LocAgent's ablation finds graph edges materially improve code-localization accuracy, the Constraint Decay paper ([arxiv:2605.06445](https://arxiv.org/html/2605.06445v1)) finds agents lose ~30 points in pass rate as architectural constraints accumulate (Clean Architecture layering alone costs -9.1 points, on the open and mid-tier models tested) and that its ground-truth layer/dependency-direction verifier is essentially `archy check`, and the coding-agent failure-mode literature names the specific patterns (scope drift, cross-file reasoning failure) that an architectural feedback loop is built to catch. Citations, a failure-mode-to-archy-capability mapping, and the resulting roadmap priorities are in [`docs/research/RESEARCH_METRICS.md` §14c](https://github.com/hslee16/Archy/blob/main/docs/research/RESEARCH_METRICS.md).\n\n### The underlying mechanism\n\nBeneath the empirical case is a structural one. Anthony Hobday, writing about software quality, names it precisely: \"as the number of things goes up, the number of relationships goes up even faster. Eventually it's impossible for people to properly consider all of those relationships.\" Coherence is the state where those relationships still hold together; entropy is its steady loss as a system grows. A single author keeps a codebase coherent by remembering every edge. An agent generating code at machine speed cannot, and neither can a team past a certain size.\n\nThat relationship load is exactly what archy reads. Coupling, the DSM, import cycles, and change-coupling are all measures of how far the graph has drifted from \"one person can hold it in their head.\" archy externalizes that memory into a number and a trend, so the growth in relationships stays visible instead of being discovered during a refactor that blows up.\n\n## Scope\n\n- **Python only.** The cross-language story belongs to [sentrux](https://github.com/sentrux/sentrux); that division is settled. archy goes deep on Python (transitive contracts, SDP, NCCD, `if TYPE_CHECKING:` semantics) rather than broad across languages; see [`docs/LEARNINGS.md`](https://github.com/hslee16/Archy/blob/main/docs/LEARNINGS.md) §\"Competitive landscape\".\n- **Tree-sitter powered.** Robust to in-flight edits and partial files; survives syntax errors that would crash `ast`.\n- **Score that trends over time.** A single number per commit, persisted, plotted. Trend matters more than the absolute value.\n- **Rules as YAML.** \"Layer X cannot import Y.\" No DSL, no plugins (yet).\n\n## Non-goals\n\n- Multi-language analysis\n- Replacing linters, type checkers, or test runners\n- Generating code or auto-fixing violations\n\n## Quick start\n\nCovered above in [Start in one command](#start-in-one-command); this section is the detail behind it.\n\n**Requires Python 3.10+** (archy depends on `mcp>=1.28.1` which is 3.10-only). If you only have system Python 3.9 or older, install a newer Python first or use [uv](https://docs.astral.sh/uv/), which manages versions for you and is what `uvx` comes from.\n\n```bash\npip install archy\n# or: uv tool install archy\n# or: pipx install archy\n# or nothing at all: prefix any command with `uvx`, e.g. `uvx archy score .`\n```\n\nUsing archy as an MCP server inside an AI coding agent? Skip the manual config and run `uvx archy install`, which wires it into Claude Code, Cursor, Codex, opencode, or Continue automatically and writes a config that invokes `uvx archy mcp`, so archy never needs to be on your PATH. See [`docs/INSTALL.md`](https://github.com/hslee16/Archy/blob/main/docs/INSTALL.md).\n\nAll examples below use the installed `archy` command. If you're working from a checkout, prefix them with `uv run` (e.g. `uv run archy graph .`).\n\nSee [`docs/SIXTY_SECOND_TOUR.md`](https://github.com/hslee16/Archy/blob/main/docs/SIXTY_SECOND_TOUR.md) for the copy-paste path from zero to first score.\n\n### Inspect the graph\n\n```bash\narchy graph path/to/project --internal-only\narchy graph path/to/project --format json > graph.json\narchy graph path/to/project --format dot | dot -Tsvg > graph.svg\n```\n\n### Find import cycles\n\n![Three modules ranked by dependency depth, where pkg.a imports pkg.b and pkg.b imports pkg.c, and a back-edge from pkg.c to pkg.a closes a cycle.](https://raw.githubusercontent.com/hslee16/Archy/main/docs/assets/diagrams/import-cycle.png)\n\nRanking the modules is what makes a cycle visible: every ordinary import points down a rank, so the one edge pointing back up is the entire finding.\n\nTarjan SCCs of size >= 2, plus self-loops (a module importing itself). Use `--strict` in CI to fail on any cycle.\n\n```bash\narchy cycles path/to/project\narchy cycles path/to/project --format json\narchy cycles path/to/project --strict\n```\n\n### Enforce layer rules\n\nReads `archy.yaml` from the repo root. Exits 1 on any violation. See [Layer rules](#layer-rules-archy-check) below.\n\n```bash\narchy check path/to/project\narchy check path/to/project --format json\narchy check path/to/project --config custom.yaml\n```\n\n### Transitive contracts (`archy contracts`)\n\n`archy check` only sees direct edges. `archy contracts` wraps [import-linter](https://import-linter.readthedocs.io/) so the same layer story is enforced *transitively* (A → B → C still counts as A reaching C). It is the strictness upgrade for projects whose layers leak through indirect paths.\n\n```bash\npip install 'archy[contracts]'\narchy contracts path/to/project\narchy contracts path/to/project --format json\n```\n\n`archy check --contracts` runs this same transitive verdict inline, nested under the check output. It never changes `check`'s own exit code: a flag that can turn a passing check into a failing one because an optional dependency is absent would be unsafe to leave on in CI. Use the standalone `archy contracts` when the transitive result should itself gate the build.\n\n**A kept contract is not automatically protection.** A contract whose module expressions match nothing in the graph holds no matter what the code does, so `all_kept` calls it kept while nothing was ever checked. `archy contracts` exits non-zero on `verified` (evaluated *and* held), not on `all_kept`, and `archy check --contracts` reports `transitive_checked: false` for the same reason: a rule that could not have failed was not evaluated. The text output marks such a contract `??` rather than `OK` and names the expressions that matched no module; `--format json` adds top-level `verified` and `unverifiable` alongside `kept`/`broken`, and per-contract `matched_nothing` and `unmatched_expressions`. A `.importlinter` `type = layers` contract needs no such flag: import-linter itself refuses to run when a required layer's module is absent, which archy reports as a config error, and an optional layer (written `(name)`) is absent by design.\n\n**Config resolution.** `archy contracts` reads, in order:\n\n1. The `--config` argument if passed.\n2. `.importlinter` in the project root: the **canonical** contracts config.\n3. `archy.yaml`: best-effort fallback. Each `forbid:` rule becomes one Forbidden contract checked transitively. Emits a `UserWarning` because this path cannot express `ignore_imports`, so any legitimate transitive edge (e.g., a service layer reaching `psycopg` *through* a sanctioned `app.libs.db.*` module) will be reported as a violation with no way to whitelist it.\n\nTwo configs, one concern each:\n\n- **`archy.yaml`** owns layer definitions, direct-edge gating (`archy check`), required-reach rules (`required:`), `sdp:`, `exclude:`, and `roots:`.\n- **`.importlinter`** owns transitive contracts: all five contract types (Forbidden, Layers, Independence, Protected, AcyclicSiblings) and `ignore_imports` whitelists.\n\nReach for `.importlinter` as soon as you need transitive enforcement at all; the archy.yaml fallback is a zero-config onramp, not a feature target. See [`.importlinter`](https://github.com/hslee16/Archy/blob/main/.importlinter) in this repo for a real-world example, and the [import-linter contract types reference](https://import-linter.readthedocs.io/en/stable/contract_types.html) for the full grammar.\n\nCommon case: forbid services from reaching `psycopg` but allow the sanctioned db library to do so:\n\n```ini\n[importlinter]\nroot_package = app\n\n[importlinter:contract:services-must-not-reach-psycopg]\nname = services must not reach psycopg\ntype = forbidden\nsource_modules =\n app.services\nforbidden_modules =\n psycopg\nignore_imports =\n app.libs.db.engine -> psycopg\n```\n\n### Compute a quality score\n\nComposite of modularity, acyclicity, depth, equality, and complexity (geometric mean of five axes). See [`docs/SCORING.md`](https://github.com/hslee16/Archy/blob/main/docs/SCORING.md) for formulas and how to interpret the breakdown. These five axes were chosen after surveying ~15 alternatives from the package-metrics literature (Martin's `I`/`A`/`D`, Lakos's NCCD, MacCormack propagation cost, Structure101 fat/tangle, reflexion models, cognitive complexity, hotspots, logical coupling, dead/duplicate-code detection); Martin's `I` and the Stable Dependencies Principle check are also shipped as a per-module diagnostic and an `archy check` rule. See [`docs/research/RESEARCH_METRICS.md`](https://github.com/hslee16/Archy/blob/main/docs/research/RESEARCH_METRICS.md) for the full validation, what was shipped, and what was deferred and why.\n\n```bash\narchy score path/to/project\narchy score path/to/project --format json\n```\n\n### Track score over time\n\nPersist per-commit scores to `.archy/history.jsonl` and chart the trend.\n\n```bash\narchy score path/to/project --record\narchy trend path/to/project\narchy trend path/to/project --last 30 --format json\n```\n\n### Regression gate\n\nFail if the current score drops more than `--strict-tolerance` (default 0.02) below the most recent recorded run.\n\n```bash\narchy score path/to/project --strict\narchy score path/to/project --strict --record # check then record\narchy score path/to/project --strict --strict-tolerance 0.0\n```\n\n### Blast radius\n\nList internal modules that transitively depend on a given file. Useful before refactoring or removing a module.\n\n```bash\narchy impact path/to/project --file app/libs/db.py\narchy impact path/to/project --file app/libs/db.py --file app/services/auth.py --format json\n```\n\n### Affected tests (CI gating)\n\n`archy affected` is the CI-shaped cousin of `archy impact`: given changed files, it returns the impacted modules pre-classified into tests and other downstream code, with a depth cap (default 5 hops) so a one-line edit doesn't fan out to thousands of nodes on a monorepo. Pipes naturally from `git diff`:\n\n```bash\ngit diff --name-only HEAD | archy affected . --stdin\ngit diff --name-only HEAD | archy affected . --stdin --quiet | xargs pytest\narchy affected . src/foo.py --filter \"tests/integration/**\" --json\n```\n\nTest classification defaults to pytest conventions (`test_*.py`, `*_test.py`, anything under a `tests/` directory); override with `--filter `. Internal modules only; vendored or third-party code is not traced.\n\n### Design Structure Matrix (`archy dsm`)\n\nThe DSM puts modules on both axes in a chosen ordering, and cell `(row=source, col=target)` is non-empty when source imports target. Reading positionally exposes properties any single scalar would hide: block-diagonal cohesion under community grouping, above-diagonal back-edges under topological ordering, off-block layer leakage under layer grouping. Visualization-only ([`docs/research/DSM_EMPIRICS.md`](https://github.com/hslee16/Archy/blob/main/docs/research/DSM_EMPIRICS.md) for why no scalar joins the score).\n\n```bash\narchy dsm path/to/project --group community # block-diagonal orientation\narchy dsm path/to/project --group topological # back-edges sit above diagonal\narchy dsm path/to/project --group layer --weight calls # cross-layer call traffic\narchy dsm path/to/project --focus pkg.module --focus-depth 1 # focal neighborhood\narchy dsm path/to/project --format json > .archy/dsm-before.json\n# ... edit code ...\narchy dsm path/to/project --group topological --diff .archy/dsm-before.json\n# prints any new back-edges the edit introduced\n```\n\n`archy dsm` refuses ASCII rendering for projects larger than `--max-nodes` (default 80) with an actionable error pointing at `--focus`, `--package`, or `--format json`.\n\n### Static HTML export (`archy render`)\n\nEvery other archy surface targets the agent. `archy render` targets the human reviewing what the agent did: a single self-contained HTML file to attach to a PR, drop in docs, or open offline. No JavaScript, no CDN, no vendored bundle, no server, and byte-stable for a fixed input, so two exports diff cleanly.\n\n```bash\narchy render path/to/project --view dsm --out dsm.html # the matrix, flagged cells in red\narchy render path/to/project --view dsm --group topological --out cycles.html\narchy render path/to/project --view trend --out trend.html # five axes over .archy/history.jsonl\narchy render path/to/project --view dsm # HTML to stdout\n```\n\nWhat red means follows the ordering you asked for, because only one ordering encodes it: under `--group=topological` red is a back-edge (a cycle seed), and under `--group=community` or `--group=layer`, where block order is not a dependency order, red is an edge crossing a block boundary. The DSM view refuses matrices larger than `--max-nodes` (default 300) rather than writing an unreadable file.\n\nThere is no `graph` view. A node-link diagram is the one view that needs a vendored layout engine, and it is also the lowest-signal of the three; it stays deferred behind a usage signal (see [`docs/SPEC_VISUALIZATION.md`](https://github.com/hslee16/Archy/blob/main/docs/SPEC_VISUALIZATION.md)).\n\n### Snapshot and diff (agent feedback loop)\n\nCapture a baseline at the start of an editing session, then diff after edits to see exactly which cycles or layer rules changed. See [`docs/AGENT_LOOP.md`](https://github.com/hslee16/Archy/blob/main/docs/AGENT_LOOP.md) for the full playbook (also available via the MCP server's `loop` prompt).\n\n```bash\narchy snapshot path/to/project # writes .archy/baseline.json\n# ... edit code ...\narchy diff path/to/project # risk-weighted summary + score deltas + added/resolved cycles & violations\n```\n\n### Run as an MCP server\n\nStdio transport, so AI agents can call archy directly. See [MCP server](#mcp-server-archy-mcp) below.\n\n```bash\narchy mcp\n```\n\n## MCP server (`archy mcp`)\n\nThe server is backed by a persistent parse cache (`.archy/index.db`): each tool call re-parses only the files whose content changed since the last call, so warm graph builds stay in the low seconds even on very large repos (benchmarked: 21.5s cold to 2.5s warm on Home Assistant's 17,299 modules). The cache is transparent and disposable; deleting `.archy/index.db` only costs one cold rebuild. The graph is always re-derived from the current files, so a cached result is never stale. `archy index sync` warms it explicitly; `archy index clear` removes it.\n\n`archy mcp` exposes thirteen tools and one prompt to MCP-aware AI agents (Claude Code, the Anthropic API, etc.):\n\n| Tool | Purpose |\n|---|---|\n| `archy_score` | Compute the five-metric score (modularity, acyclicity, depth, equality, complexity, geometric mean); optional `record=True` and `strict=True` for the same regression-gate behaviour the CLI offers. Pass `record=True` to record a start-of-session baseline (replaces the removed `archy_record_baseline`). `view=\"history\"` returns the recent score history from `.archy/history.jsonl` (up to `last_n` rows, oldest-first, for comparing deltas over time; replaces the removed `archy_trend`). |\n| `archy_cycles` | Find import cycles. |\n| `archy_check` | Run direct-edge layer rules from `archy.yaml`. Pass `contracts=True` to also run the transitive import-linter contracts (Layers, Forbidden, Independence, Protected, AcyclicSiblings; stricter than the direct edges), nested under the `contracts` field (replaces the removed `archy_contracts`; requires `archy[contracts]`, and degrades to `available=false` with an advisory if the extra is absent). Contracts are skipped when no `archy.yaml` is found (you get a `CheckErrorPayload` first). Always returns `coverage`: how many modules and import edges the rules actually reach, so `passed=true` can be told apart from a config that governs almost nothing. `transitive_checked` says whether this run actually evaluated the `forbid` rules transitively; it is false when contracts were never requested, when they produced no verdict, and when any contract could not have failed, since none of the three evaluated the rules. `transitive_unverified_reason` then says which, naming `archy_check(contracts=True)` if it was never requested, the actual failure if it produced no verdict, and how many contracts matched nothing if that is what happened. So a clean pass is never silent about having seen direct edges only. `min_layers_present:` in `archy.yaml` also gates `passed` here, not just the CLI exit code. `required_violations` reports unsatisfied `required:` rules (module X must transitively reach Y, counting the implicit package-`__init__` import), and gates `passed` too; fix by adding the missing import, not by deleting the rule. Within `contracts`, read `verified`, not `all_kept`: a contract whose module expressions match nothing in the graph is `kept` because it could not have failed, `unverifiable` counts those, and each one carries `matched_nothing` and `unmatched_expressions` naming the patterns that matched no module. |\n| `archy_impact` | Given changed file paths, return what they affect. `mode=\"blast\"` (**default**) returns the modules that transitively import them (blast radius), plus `chains`: the shortest import path back to a changed module (with line numbers) explaining why each is impacted. `mode=\"affected\"` (replaces the removed `archy_affected`) is the CI-shaped lookup instead: modules pre-classified into `impacted_tests` and `impacted_modules`, depth-capped (default 5 hops) so a single-line edit doesn't fan out to thousands of nodes; `test_filter` overrides pytest test detection with a recursive glob. `co_change=true` (blast mode, opt-in) adds a `co_changed` list: modules that historically co-change with the edit in git but have no import/call edge to it, so the structural blast radius misses them (`archy coupling` scoped to your edit; source-only, best-effort, the only path that reads git). |\n| `archy_snapshot` | Capture score, cycles, and violations to `.archy/baseline.json`. Call at session start. Also returns an `invariant_brief` (declared layers, forbidden edges, declared `required:` reach rules, acyclic invariant, baseline score, load-bearing modules) to read before the first edit. |\n| `archy_diff` | Compare current state against the snapshot; returns added/resolved cycles & violations, per-component score deltas, and a risk-weighted `summary` whose items carry a `prompt` reframing each delta as a judgment question (\"new cycle a -> b; intended, or invert an edge?\"). |\n| `archy_simulate` | Counterfactual pre-edit check: given a proposed import-edge delta (`add`/`remove` of `{from, to}` pairs), return the would-be cycles, back-edges, layer/SDP/required-reach violations, per-axis score delta, and blast-radius change, with no file written. Test a refactoring hypothesis before committing to it. |\n| `archy_graph` | Inspect the dependency graph. With no `focus`, `response_format=\"summary\"` (**default**) returns the top-N overview by fan-in / fan-out / PageRank plus top external deps (replaces the removed `archy_graph_summary`; `top_n` controls N); `response_format=\"full\"` returns the complete node/edge dump matching `archy graph --format json`, refusing graphs larger than `max_nodes` (default 500) with an explicit `GraphTooLargePayload`. Pass `focus=[...]` (replaces the removed `archy_graph_focus`) for a bounded subgraph around one or more modules (qualnames or file paths): `depth` caps hops, `direction` is `in`/`out`/`both`, each edge carries import line numbers, and `response_format`/`max_nodes`/`top_n` do not apply. |\n| `archy_what_to_refactor_next` | Ranked refactor-priority list (replaces the removed `archy_hotspots` and `archy_high_risk_modules` via `lens`). `lens=\"fused\"` (**default**) sums the behavioral lens (CC x churn) and the structural lens (edit-risk: central+fragile) into a `priority`, so a module flagged by *both* generally outranks a comparable single-lens one (a dominant single-lens signal can still rank first). `lens=\"behavioral\"` ranks CC x churn hotspots only (needs git); `lens=\"structural\"` ranks the edit-risk composite only (git-free; pass `min_risk=0` for no floor). Each entry names which lenses fired and carries a one-line `rationale`. An empty list plus a `note` is a real answer. |\n| `archy_dsm` | Design Structure Matrix view of the import graph. `response_format=\"summary\"` (**default**) returns a compact overview (block structure, counts, back-edges, cross-block coupling) without the full cell list. `response_format=\"full\"` returns the positional matrix (cell `(row=source, col=target)` non-empty when source imports target), refusing matrices over `DEFAULT_MAX_DSM_CELLS` cells with a `DSMTooLargePayload`. `group_by` controls row/col ordering (`community` for block-diagonal cohesion, `layer` for layer-violation forensics, `topological` to localize back-edges). `weight` is `imports` or `calls`. Narrow large projects with `focus=` + `focus_depth` or `package=`. When `baseline_path` is provided, returns a structured diff (regardless of `response_format`) whose `new_back_edges` field flags cycles the edit just introduced. Visualization-only; see [`docs/research/DSM_EMPIRICS.md`](https://github.com/hslee16/Archy/blob/main/docs/research/DSM_EMPIRICS.md). |\n| `archy_duplicates` | Cluster functions with identical normalized body shape into two tiers: `duplicates` (likely-real, investigate) and `variants` (demoted likely-intentional clusters - same-class / boilerplate / test / vendored / `independent`, each with a `variant_reason`). `co_change=true` (**default**, needs git) adds the `independent` demotion: copies in actively-maintained files that never co-change (deliberately parallel implementations), the principled precision lever that lifts the primary tier above the ~50% syntactic ceiling (§12f). Within the primary tier, `exact=true` marks byte-identical (Type-1) clusters, the highest-confidence subset. `near_miss=true` (opt-in, slower) adds a lower-confidence `near_miss` tier: Type-3 (gapped) clones the exact shape-hash misses, found by token-multiset overlap (§12h). `response_format=\"summary\"` (**default**) returns ranking fields + one sample member per cluster; `\"full\"` returns member lists. Advisory surfacer, not a score axis: refactorability is a semantic call (see [`docs/research/RESEARCH_METRICS.md`](https://github.com/hslee16/Archy/blob/main/docs/research/RESEARCH_METRICS.md) §12c/§12f/§12h). `min_nodes` (default 30) skips trivial stubs. |\n| `archy_conventions` | Report the project's own house style, derived from its source: `naming` (class-name suffix families grouped by **home module**, so the module you are about to edit shows its own patterns), `surfaces` (mirrored helper sets like `_x_to_text`/`_x_to_json`, plus names defined in several modules - the \"wire all of these together\" list), `gates` (sites where a **failed finding** exits non-zero, each with its literal exit `code` and controlling lever: `flag:--strict`, `config:`, `param:`, `hardcoded`), `errors` (the separate user-error exits - bad config, missing file - kept apart so the gate count stays meaningful), `models` (base-class / frozen / tuple-vs-list census), `bases` (kind families grouped by what they derive from *transitively*, counting only bases the project defines, with suffix agreement reported so a family whose name is not the rule says so), `registries` (`NAME = Ctor(...)` families and the distribution of every keyword passed - how a project declares codes or flags when it does not use classes), `export_gaps` (members absent from an `__all__`, or from a `from .x import Y as Y` block, that already lists their siblings) and `doc_gaps` (members the project's own `.rst`/`.md` surface does not name). Call before adding a class, field, or command to a project you do not know. Advisory: never fails, mutates nothing. `min_family` (default 2) raises the reporting floor; `include_tests` censuses test modules too (default false, because test fixtures dilute a real family). |\n| `archy_module_view` | Everything known about ONE module, complete and unranked - the **lookup** counterpart to `archy_conventions`'s ranked report. Because the report truncates, a module's absence from it means nothing; every list here is complete for the module named, so absence is the answer to \"does `risk` import `hotspots`\" or \"does anything still reach `layers`\". Returns `imports_internal` (relative imports resolved), `imported_by` (counting test importers even when tests are otherwise set aside, because a module imported only by tests is imported), `classes`, `functions`, `exports` (null when the module declares no `__all__` and no explicit re-exports - different from an empty one), `suffix_families`, `gates`, and `status`, which says whether the module was censused or set aside and why, so an empty view is never mistaken for \"nothing to report\". An unknown module name raises rather than returning an empty view. Advisory: never mutates. |\n\nThe server also exposes a `loop` **prompt** with the agent feedback-loop playbook (snapshot at start, impact before edit, diff after edit). Discoverable via the standard MCP `prompts/list` call. See [`docs/AGENT_LOOP.md`](https://github.com/hslee16/Archy/blob/main/docs/AGENT_LOOP.md) for the human-readable version.\n\nThe `archy mcp` server still keeps a debounced filesystem watcher warming `.archy/index.db` so graph builds stay fast, and every tool syncs on demand so a result is never stale. The index-freshness readout that used to be the `archy_status` MCP tool is now the CLI `archy index status` (#267): freshness is diagnostic plumbing an agent rarely needs mid-task, not a per-edit decision.\n\n#### Tool output contract (structured output)\n\nEvery tool declares an `outputSchema` (JSON Schema, derived from its return model) in `tools/list`, and every `tools/call` returns both a `structuredContent` object (validated against that schema) and a text block with the same JSON, per the [2025-06-18 MCP structured-output spec](https://modelcontextprotocol.io/specification/2025-06-18). All tools are also annotated `readOnlyHint: true` (closed-domain, idempotent, non-destructive), so trusted clients can auto-approve archy's calls instead of prompting on every read. Sequence returns (`archy_cycles`, `archy_score(view=\"history\")`) and union returns (`archy_diff`, `archy_graph`, `archy_dsm`) are wrapped under a top-level `result` key since `structuredContent` must be a JSON object; for unions every branch (including the in-band `*ErrorPayload` shapes) is a conforming `anyOf` member.\n\n#### Error model (recovery contract)\n\narchy maps failures onto MCP's two error mechanisms with one convention, so an agent has a single recovery contract:\n\n- **Usage error → `isError: true`** (a raised exception): an invalid argument *value* (e.g. `response_format=\"xml\"`, `last_n=0`), a *malformed* `archy.yaml`, or a project over the scan ceiling. The caller must fix the call or the environment.\n- **Recoverable / advisory → in-band result (`isError: false`)**: an expected precondition that isn't met but is recoverable, or a valid-but-degraded result. These are normal results the agent branches on. Either a **union variant** when there's no usable result (no baseline → `DiffErrorPayload`, output too large → `*TooLargePayload`, no config → `CheckErrorPayload`, no DSM snapshot → `DSMErrorPayload`), or an **advisory field** on an otherwise-valid payload (`ContractsPayload.available=false`, `WhatToRefactorPayload.git_available` / `WhatToRefactorPayload.note`). The marker for a \"no usable result\" variant: a payload with an `error` field and no success data.\n- **Protocol error (JSON-RPC)**: unknown tool or a missing/mistyped required argument, handled by the framework.\n\n#### Wiring it into your agents\n\nOne command detects your installed clients (Claude Code, Cursor, Codex CLI, opencode, Continue) and wires each one up:\n\n```bash\nuvx archy install # detect, confirm, register the MCP server in each client\nuvx archy uninstall # the exact inverse; --dry-run to preview\n```\n\nThis registers the `uvx archy mcp` server, drops a short rules file so the agent knows when to call the tools, and (on Claude Code) seeds the `permissions.allow` allowlist. It does not install a binary or the Claude plugin. The full guide, including the per-client path matrix, the manual stanza for unknown clients, plugin-vs-installer guidance, and troubleshooting, is in **[`docs/INSTALL.md`](https://github.com/hslee16/Archy/blob/main/docs/INSTALL.md)**.\n\nThe lowest-friction path specifically on Claude Code is the bundled plugin at [`plugins/claude/`](https://github.com/hslee16/Archy/blob/main/plugins/claude/): `/plugin marketplace add hslee16/archy` then `/plugin install archy@archy` from inside Claude Code (or `claude --plugin-dir /path/to/archy/plugins/claude` from a checkout). See [`docs/INSTALL.md`](https://github.com/hslee16/Archy/blob/main/docs/INSTALL.md#plugin-vs-installer-which-should-i-use) for when to prefer it over the installer.\n\n### Regression-gate semantics\n\n`--strict` reads the last row from `.archy/history.jsonl` and compares the current score against it. Drops beyond the tolerance fail with exit code 1. The default tolerance (0.02) matches the threshold sentrux's `gate` uses. This gives archy parity with sentrux's regression-gate use case while keeping the long-term JSONL history for `archy trend`.\n\n## CI integration\n\n### GitHub Action\n\narchy ships a composite action you can drop into any workflow:\n\n```yaml\n- uses: hslee16/archy@v0.46.2\n with:\n command: score # score | check | cycles\n path: .\n strict: \"true\" # fail on regression (score) or any cycle (cycles)\n```\n\nInputs (all optional unless noted):\n\n| Input | Default | Notes |\n|---|---|---|\n| `command` | `score` | `score`, `check`, or `cycles` |\n| `path` | `.` | Project root to analyze |\n| `strict` | `true` | `score`/`cycles`: fail on regression / any cycle |\n| `strict-tolerance` | `0.02` | `score --strict` tolerance |\n| `record` | `false` | `score`: append result to `.archy/history.jsonl` |\n| `config` | (auto) | `check`: path to `archy.yaml` |\n| `python-version` | `3.10` | Python to install |\n\n### Pre-commit hook\n\nAdd to `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/hslee16/archy\n rev: v0.46.2\n hooks:\n - id: archy-check # layer rules from archy.yaml\n - id: archy-score-strict # regression gate against last recorded score\n - id: archy-cycles # fail on any import cycle\n```\n\n`archy-score-strict` reads `.archy/history.jsonl`; commit a baseline first with `archy score . --record`.\n\n## Layer rules (`archy check`)\n\nDrop an `archy.yaml` at the repo root declaring layers and forbidden directions:\n\n```yaml\nlayers:\n domain:\n modules:\n - \"myapp.domain.**\"\n application:\n modules:\n - \"myapp.application.**\"\n infra:\n modules:\n - \"myapp.infra.**\"\n - \"myapp.adapters.**\"\n\nforbid:\n - {from: domain, to: application}\n - {from: domain, to: infra}\n - {from: application, to: infra}\n```\n\n**Pattern syntax.** Dotted-name globs: `*` matches one segment, `**` matches zero or more. `myapp.domain.**` covers the package itself and every descendant. Modules must belong to at most one layer.\n\n**Required reach (`required:`).** The inverse of `forbid:`. A forbid rule catches an edge that should not exist; a required rule catches one that should exist and does not, which forbidding cannot express:\n\n```yaml\nrequired:\n - source: \"app.commands.*\"\n must_reach: app.core.database.model_registry\n reason: standalone entrypoints need the full mapper registry\n```\n\nEvery module matching `source` must **transitively** reach `must_reach`, counting the implicit package-`__init__` import Python guarantees (importing `a.b.c` runs `a/b/__init__.py` first). So one import in `app/commands/__init__.py` satisfies the rule for every command module, which is usually the correct fix -- a direct-import rule would report all of them as violations *after* that fix.\n\nThis came from a production incident: 34 command modules run standalone, each needing a SQLAlchemy model registry imported before first mapper configuration. 11 imported it, 21 crashed at runtime, and 2 passed only because they happened to reach it through unrelated imports. Those 2 are why the rule is defined over reach rather than imports.\n\n`reason` is carried into every output surface, because \"X does not reach Y\" is a fact about the graph and not an explanation, and a rule nobody can justify gets deleted rather than satisfied. A rule whose patterns match nothing is reported as a violation, not passed over. Note `pkg.**` includes `pkg/__init__.py` itself; use `pkg.*` to scope the rule to submodules.\n\nBe honest about what this does: archy cannot *derive* such a requirement (that is framework semantics, not graph structure). Someone has to know the constraint and write it down. What the rule then does is find every other module that violates it and stop the next edit from undoing the fix -- a ratchet, not a detector.\n\n**Excluding directories.** Add an optional `exclude:` list of directory basenames to skip codegen output, vendored code, etc. Each name is matched anywhere in the project tree (same mechanism as the built-in skips for `.venv`, `node_modules`, `__pycache__`):\n\n```yaml\nexclude:\n - baml_client\n - generated\n```\n\n`exclude:` applies to every analysis (`graph`, `cycles`, `score`, `check`) and the equivalent MCP tools.\n\n**Scan-size guard (`max_modules:`).** archy refuses to *start* a scan of a tree with more modules than a ceiling, so a stray vendored, cache, or generated directory that the named `exclude:` skips do not cover cannot silently wedge a scan for minutes. The default (10,000) sits well above the largest real projects; a scan that trips it stops with a message pointing at `exclude:` / a narrower path. Override or disable it:\n\n```yaml\nmax_modules: 25000 # raise the ceiling for a genuinely large monorepo\n# max_modules: 0 # disable the guard entirely\n```\n\n**Namespace packages (`roots:`).** archy discovers packages by walking `__init__.py` files. PEP 420 namespace packages (no `__init__.py`) are invisible by default. Declare them as roots so descendants get qualified names:\n\n```yaml\nroots:\n - app # `app/main.py` becomes `app.main`\n - src/service # `src/service/db.py` becomes `service.db`\n```\n\nWithout `roots:`, a project like `app/libs/db.py` (no `app/__init__.py`) is either skipped entirely or shows up as a top-level `libs.db`, which makes layer rules like `app.libs.**` match nothing.\n\n**Layer presence (`min_layers_present:`).** Forbidding edges *between* layers says nothing about whether the layers exist. A codebase that collapsed four layers into one module satisfies every `forbid` rule by having no cross-layer edges at all, and passes silently. Set a floor to catch that:\n\n```yaml\nmin_layers_present: 3 # at least 3 of the declared layers must contain a module\n```\n\nEmpty declared layers are reported either way, because every rule naming one is dead:\n\n```console\n# layers present: 2 of 4 declared; empty: repositories, models\n# FAIL: 2 layer(s) present, min_layers_present is 3\n```\n\nUnset by default, so existing configs keep their exit codes. The shape is taken from the Constraint Decay paper ([arxiv:2605.06445](https://arxiv.org/abs/2605.06445)), whose architecture verifier pairs a dependency-direction rule with exactly this presence floor (\"at least 3 of the 4 canonical layers present as distinct directories\"). `bench/fixtures/conduit_clean/` reproduces its three cases.\n\n**It is a backstop, not the main event, and the measurement says so.** Across 50 agent-generated backends, every single one produced all four layer directories: this check never fired once, while the direction check caught every failure. Keep it for the collapsed-into-one-module case it is named for, but if you are deciding where to spend effort in a config, spend it on `forbid` rules.\n\n**Discovery.** `archy check` walks PATH upward to find `archy.yaml` unless `--config` is given. Exits 1 on violation.\n\n**Coverage.** Every `check` reports how much of your code the rules actually reach, on a pass as well as a failure:\n\n```console\n$ archy check .\n# No layer violations (config: archy.yaml).\n# layer coverage: 9 of 42 modules (21%), 16 of 117 internal edges (14%); 33 module(s) match no layer (`archy check --show-unlayered`)\n```\n\nThat line exists because **a rule set that cannot fire is indistinguishable from a clean codebase**: without it, a config governing 14% of your import edges prints the same \"No layer violations\" as one governing all of them. The edge percentage is the one to watch, since a config can put most modules in layers while ruling almost none of the edges between them. Coverage is scoped to the root packages your patterns name, so scripts and benchmarks sitting beside your package are counted separately rather than dragging the number down. `--show-unlayered` lists the modules no layer matches.\n\nThe numbers above are archy's own, and they are not flattering. They are printed here because the alternative is not knowing.\n\narchy enforces its own architecture this way; see [`archy.yaml`](https://github.com/hslee16/Archy/blob/main/archy.yaml) at the repo root and the `archy check .` step in `.github/workflows/ci.yml`.\n\n**Stability check (`sdp:`).** Optionally enable Robert Martin's Stable Dependencies Principle: a module should not import one that is *less stable* than itself. Stability is `I = Ce / (Ce + Ca)` where `Ce` is outgoing internal imports and `Ca` is incoming, so `I = 0` means \"depended on, depends on nothing\" (most stable) and `I = 1` means \"depends on lots, nothing depends on this\" (least stable).\n\n```yaml\nsdp:\n enabled: true\n tolerance: 0.0 # ignore violations within this I gap; default 0\n mode: error # 'error' fails the gate (default); 'warn' reports but exits 0\n```\n\nWhen enabled, `archy check` flags every internal import edge whose target's `I` strictly exceeds the source's (plus tolerance). Per-module `I` is also surfaced in `archy graph --format json` whether or not `sdp:` is enabled, so you can audit before turning enforcement on.\n\n**Gradual adoption.** Existing codebases will often have SDP violations on day one. Set `mode: warn` to report violations in the output (and `archy_check`'s `sdp_violations` payload) without failing the gate, then flip to `mode: error` once the count is at zero. Layer-rule violations always fail the gate regardless of `sdp.mode`.\n\n## Development\n\n```bash\nuv sync # install runtime + dev deps from uv.lock\nuv run ruff check # lint\nuv run ruff format # format\nuv run ty check # type check\nuv run pytest # tests\n```\n\nOne pytest case (`test_pagerank_matches_networkx_when_available`) compares archy's hand-rolled `_pagerank` against `nx.pagerank`, which needs numpy/scipy. The dependency is intentionally not in the default install (archy stays scientific-stack free); to run that test locally, sync the optional `parity` group:\n\n```bash\nuv sync --group parity # pulls in numpy + scipy for the parity test\nuv run pytest # the test now runs instead of being skipped\n```\n\n## Roadmap\n\n**This roadmap is closed. Nothing below is planned.** See the status note at the top of this page; [`docs/ROADMAP.md`](https://github.com/hslee16/Archy/blob/main/docs/ROADMAP.md) and [`docs/FUTURE.md`](https://github.com/hslee16/Archy/blob/main/docs/FUTURE.md) carry the same closure and the reasoning behind it.\n\nBoth phases of the index-and-install work shipped (Phase 1 install-DX in v0.25.0 / v0.26.0, Phase 2 persistent index + watcher in v0.27.0). What follows is kept as a record of what was considered and why, not as a plan. Several items rest on a premise that has since been retracted, so read [`docs/WHAT_DIDNT_WORK.md`](https://github.com/hslee16/Archy/blob/main/docs/WHAT_DIDNT_WORK.md) before picking one up. Anyone is welcome to.\n\nConsidered and never started:\n\n- **Per-module score breakdown** so an agent can ask \"did my edit make *this module* worse?\" rather than \"did the project overall regress?\". Pairs with `archy_diff`.\n- **Opt-in agent hooks (`archy install --hooks`)**: register a lifecycle hook in the agent client (Claude `Stop`, Cursor `afterFileEdit`, ...) that runs the archy gate automatically after edits, so the loop fires whether or not the agent remembers to call the tools. Spec: [`docs/SPEC_INSTALL_HOOKS.md`](https://github.com/hslee16/Archy/blob/main/docs/SPEC_INSTALL_HOOKS.md).\n- **Static fragility proxy** (high-instability x high-fan-in) as a git-free hotspot stand-in. Advisory, not a score axis. (Duplicate-function detection has shipped as the `archy duplicates` CLI command: a two-tier surfacer with a primary \"likely duplicate\" list and a demoted \"same-class / boilerplate variant\" list. A literature review confirmed ~50% refactorability precision is the expected ceiling for any similarity-only detector, so the semantic call is left to the agent; change-history co-change is the precision layer, shipped as `demote_independent` (#242) on the change-coupling machinery [#131](https://github.com/hslee16/archy/issues/131). Exposed on both the CLI (`archy duplicates`) and MCP (`archy_duplicates`, the 14th tool).)\n\nShipped:\n\n**Foundations**\n\n- Tree-sitter import graph; `__init__.py` re-export resolution; Tarjan cycle detection.\n- YAML layer rules (`archy check`); composite score (`archy score`); JSONL history + `archy trend`.\n- MCP server (`archy mcp`); GitHub Action + pre-commit hooks.\n\n**Agent loop**\n\n- Blast-radius: `archy impact`.\n- Snapshot/diff: `archy snapshot` / `archy diff` + MCP `loop` prompt.\n- Import-linter contract wrap: `archy contracts`, `archy[contracts]`.\n- Graph-navigation MCP tools: `archy_graph_focus`, `archy_graph_summary`, `archy_graph` (design in [`docs/SPEC_GRAPH_MCP.md`](https://github.com/hslee16/Archy/blob/main/docs/SPEC_GRAPH_MCP.md)).\n- Per-module `edit_risk` composite + `archy_high_risk_modules` MCP tool: geometric mean of propagation cost, normalized fan-in, and instability; surfaced on every graph payload.\n- **v0.24, risk-weighted `archy_diff` summary**: additive `DiffSummary` (`headline`, `top_regressions`, `top_improvements`) ranked by `edit_risk` so the loop-closer reads one sentence instead of re-ranking raw deltas.\n- **v0.25, `archy affected`**: depth-capped reverse-impact walk mapping changed files to impacted modules and test files (`git diff --name-only HEAD | archy affected . --stdin -q | xargs pytest`); CLI + `archy_affected` MCP tool.\n- **v0.27, persistent index + file watcher**: SQLite parse cache (`.archy/index.db`) keyed by content hash (7-9x warm-path speedup, byte-identical to a cold build) plus a `watchdog` observer that keeps the index warm inside `archy mcp`; new `archy_status` MCP tool (17th) reports `last_synced_at`.\n- **v0.28, causal-framing reframes**: archy's output now reads as causal claims and judgment prompts, not just structure. `archy_impact` returns `chains` (the shortest import path back to a changed module, with line numbers, explaining *why* each dependent is impacted); `archy_snapshot` returns an `invariant_brief` (declared layers, forbidden edges, the acyclic invariant, baseline score, and load-bearing modules) so an agent is told the constraints before its first edit; and each `archy_diff` summary item carries a `prompt` reframing the delta as a reviewer question (\"new cycle a -> b; intended, or invert an edge?\"). No new tool, axis, or graph; packaging over already-computed data ([#152](https://github.com/hslee16/archy/pull/152), [#153](https://github.com/hslee16/archy/pull/153), [#154](https://github.com/hslee16/archy/pull/154)).\n- **v0.29, `archy_simulate` (18th tool)**: counterfactual pre-edit check. Given a proposed import-edge delta (`add`/`remove` of `{from, to}` pairs), it returns the would-be cycles, new back-edges, layer/SDP violations, per-axis score delta, and blast-radius change *before any file is written*, so an agent can test a refactoring hypothesis and reshape a plan that introduces a cycle before touching code. Mostly composition over the diff/DSM/propagation machinery; empirically validated (oracle 315/315 on real repos, 96% fidelity, [`SIMULATE_ORACLE_EMPIRICS.md`](https://github.com/hslee16/Archy/blob/main/docs/research/SIMULATE_ORACLE_EMPIRICS.md), [#156](https://github.com/hslee16/archy/pull/156)).\n- **v0.30, `archy_what_to_refactor_next` (19th tool)**: one ranked refactor-priority list fusing the behavioral lens (`archy_hotspots`, CC x churn) and the structural lens (`archy_high_risk_modules`, edit-risk). The two normalized lens scores are summed into a `priority`, so a module flagged by *both* generally outranks a comparable single-lens one, while a dominant single-lens signal (a giant hotspot at the import-graph leaves) can still rank first. Each entry names which lenses fired and carries a one-line `rationale`; one call replaces two-plus-synthesis. Pure aggregation over the two existing primitives. Honest null: an empty list plus a `note` when nothing is both complex+churned and nothing is central+fragile above the `min_risk` floor, rather than manufacturing a phantom #1 ([#130](https://github.com/hslee16/archy/issues/130)).\n- **v0.36, MCP tool consolidation (#227)**: shrank the `archy mcp` surface from 19 tools to 13 by clean removal (no aliases), folding each removed tool into a survivor via a mode/lens/param switch: `archy_impact(mode=\"affected\")` absorbs the old `archy_affected`; `archy_graph(focus=...)` and `archy_graph(response_format=\"summary\")` absorb `archy_graph_focus` and `archy_graph_summary`; `archy_what_to_refactor_next(lens=\"behavioral\"|\"structural\")` absorbs `archy_hotspots` and `archy_high_risk_modules`; and `archy_score(record=True)` replaces `archy_record_baseline`. A smaller, less-overlapping surface costs fewer always-in-context tokens and improves tool-selection accuracy. BC-breaking, so the plugin pin moved to `archy>=0.36,<1.0`. The CLI is unchanged. Closes the [#230](https://github.com/hslee16/archy/issues/230) modernization tracker ([#227](https://github.com/hslee16/archy/issues/227)).\n- **v0.35, MCP surface modernization**: brought the `archy mcp` tools up to current MCP best practice (2025-2026 spec) without changing the tool set (still 19, no plugin-pin bump). All tools now declare `readOnlyHint` / `title` annotations so trusted clients can auto-approve archy's read-only calls instead of prompting on every read ([#225](https://github.com/hslee16/archy/issues/225)); every tool declares a structured-output `outputSchema` and returns conforming `structuredContent` alongside the text block ([#228](https://github.com/hslee16/archy/issues/228)); the token-heavy `archy_dsm` and `archy_graph` are concise-by-default with a `response_format=\"summary\"|\"full\"` enum and a truncation cap (DSM summary ~89% smaller than the full matrix) ([#226](https://github.com/hslee16/archy/issues/226)); and a single three-tier error model gives agents one recovery contract (`isError:true` for usage errors, in-band result variants for recoverable conditions like no-baseline / too-large / no-config) ([#229](https://github.com/hslee16/archy/issues/229)). No new tool, axis, or graph; MCP-DX over the existing surface. Tracker [#230](https://github.com/hslee16/archy/issues/230).\n- **v0.37, duplicate-function detection** ([#133](https://github.com/hslee16/archy/issues/133)/[#242](https://github.com/hslee16/archy/issues/242)): a new CLI command `archy duplicates` and MCP tool `archy_duplicates` (14th) that cluster functions with an identical normalized body shape (tree-sitter AST-shape hashing, folded into the existing complexity walk, no new parse). Output is a two-tier surfacer: a primary \"likely duplicate\" list and a demoted \"same-class / boilerplate variant\" list (a semantic de-noiser using same-class / `@overload` / trivial signals), with `exact=true` flagging byte-identical (Type-1) clusters as the highest-confidence subset. Advisory only, never a score axis. Deliberately framed as a *surfacer*, not a precision oracle: a 94-source literature review + a 12-repo false-positive validation established that ~50% refactorability precision (~63% on the exact tier, ~74% on non-test source) is the expected ceiling for any similarity-only detector, so the semantic call is left to the reader/agent. Change-history co-change ([#131](https://github.com/hslee16/archy/issues/131)), path-scoping ([#247](https://github.com/hslee16/archy/issues/247)), and a Type-3-tolerant primitive ([#246](https://github.com/hslee16/archy/issues/246)) are the queued precision/recall follow-ups. Additive tool, so the plugin pin stays `archy>=0.36,<1.0`. Empirics: [`RESEARCH_METRICS.md` §12b-§12d](https://github.com/hslee16/Archy/blob/main/docs/research/RESEARCH_METRICS.md).\n- **v0.38, change coupling** ([#131](https://github.com/hslee16/archy/issues/131)): a new CLI command `archy coupling` that ranks module *pairs* which co-change in git history but have no import/call edge - behavioral (temporal) coupling the structural graph can't see (Tornhill / CodeScene lineage, reusing the `archy hot","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":104,"_105":106},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[],"license","MIT","language","Python","registryName","io.github.hslee16/archy","homepage","https://github.com/hslee16/archy","packages",[107],{"_108":109,"_110":21,"_70":71},"registryType","pypi","identifier","ENV",{"_113":114,"_115":116,"_117":118},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]