archy

Your folders show your architecture. Your imports decide it.

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.

[!IMPORTANT]

Status, 2026-09-10: active, and pointed at the loop rather than the surface area.

What archy does. One graph, two front ends. It parses a Python project's

imports and calls once, keeps the parse cached, and answers the questions a

file tree cannot: what does this change reach, which tests does that affect,

where are the cycles, and does the graph still agree with the layers you

declared. It runs as a CLI in CI and as an MCP server inside an agent session,

off the same graph either way, and it *fails* when the declared architecture

and the real one disagree.

Where it is going: deeper into that loop, not wider. The local-model

question that reopened this project on 2026-09-02 is **closed, as six

interventions, none positive**, two of them measured as costing MORE than

their control. The write-up is Study 8 in

docs/WHAT_DIDNT_WORK.md, and it is the fifth

pre-registered null published here. The feature that line produced,

conventions --emit-headers, is kept, because it is derived rather than

hand-authored, cheap, and --check stops it rotting. Only the claim attached

to it is retired.

**What those six nulls did establish is where the failure lives: delivery and

retrieval, not capability.** Across 132 agent transcripts on a pinned tree,

read fired in 132 of 132 runs with a median of 9.5 calls before the first

edit; archy fired in 84 of 132, with a median of zero calls before it.

Every archy surface is pull. The model reaches for it after it has already

decided, or not at all. Two payloads pushed through the one channel archy

owns, the file itself, both came out more expensive than their control, which

is evidence about the channel and not the content.

So the working design rule is: **put the answer in the default output of a

command that is already being run**, rather than adding a surface that has to

be discovered first. The live threads follow from it. One is the vacuity

family: a check that could not have failed must not report like one that was

evaluated and held, which is now explicit on the contracts result and is being

finished across the remaining surfaces. The other is two structural refactors

of archy's own code: the module its own tools rate as central and fragile,

and the two files that have grown large enough to hide things. New tools and

new output formats stay gated behind a usage signal.

The discipline does not relax because the project is active. Thresholds

are pre-registered before a run, and any result, including another null, gets

published in docs/WHAT_DIDNT_WORK.md like the

five before it. Nothing archy ships today claims a local-model benefit;

archy brief (v0.46) shipped explicitly on judgment ahead of that

measurement rather than on one, and the measurement did not later rescue it.

What is not changing. The original use case is still supported and still

works: layer governance in CI, blast radius and affected-tests for a frontier

agent, the MCP server. Nothing is being removed or renamed. Bugs still get

fixed, pull requests still get reviewed, and the good first issue tickets

are still deliberately left open.

Read this first: I measured the premise, and it was wrong

I 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.

So: 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.

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.

That 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.

What that means for what gets built. Feature work premised on "agents will wreck your architecture" went off the table when that premise was retracted, and nothing since has put it back. What survives is narrower and has a number behind it: directional rules, transitive contracts and cycle detection, checked every session. That is a real job and archy does it. What the studies argue against is *more* of it: five of them produced no evidence that another feature is the missing piece, and the honest reading of headroom-limited results is that the next one will not be either.

So the roadmap that was closed in July stays closed, and being active again did not reopen it. Work here goes into the loop that survived rather than into the list that did not: making what archy already computes arrive where an agent will actually read it, and saying honestly what each answer does and does not cover. Bugs get fixed and contributions are welcome, as before.

The 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. If you only read one thing here, read that.

The failure it catches

Nothing 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.

Here 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:

# src/archy/graph.py

from archy.cli import main # convenience import. The diff looks harmless.

$ uvx archy check .

1 layer violation(s) (config: /path/to/archy/archy.yaml)

graph -> cli (forbidden): archy.graph -> archy.cli (line: 40)

layer coverage: 10 of 48 modules (21%), 21 of 137 internal edges (15%); 38 module(s) match no layer (archy check --show-unlayered)

116 scanned module(s) sit outside every declared root package and are not counted above

$ echo $? 1

$ uvx archy cycles .

1 cycle(s) found

Cycle of 12 module(s):

• archy.affected
• archy.cli
• archy.conventions
• archy.duplicates
• archy.graph
• archy.headers
• archy.impact
• archy.index
• archy.mcp
• archy.scan_config
• archy.simulate
• archy.watcher

Edges: archy.affected -> archy.impact (line: 29) archy.cli -> archy.affected (line: 27) archy.cli -> archy.conventions (line: 34) archy.cli -> archy.duplicates (line: 66) archy.cli -> archy.graph (line: 74) archy.cli -> archy.headers (line: 82) archy.cli -> archy.impact (line: 87) archy.cli -> archy.index (lines: 1537, 1538, 1566, 1591) archy.cli -> archy.mcp (line: 1511) archy.cli -> archy.scan_config (line: 111) archy.cli -> archy.simulate (line: 113) archy.conventions -> archy.graph (line: 72) archy.duplicates -> archy.graph (line: 84) archy.graph -> archy.cli (line: 40) archy.headers -> archy.conventions (line: 44) archy.headers -> archy.graph (line: 45) archy.impact -> archy.graph (line: 28) archy.index -> archy.graph (line: 31) archy.mcp -> archy.affected (line: 117) archy.mcp -> archy.conventions (line: 119) archy.mcp -> archy.duplicates (line: 157) archy.mcp -> archy.graph (line: 166) archy.mcp -> archy.impact (line: 182) archy.mcp -> archy.scan_config (line: 202) archy.mcp -> archy.simulate (line: 204) archy.mcp -> archy.watcher (line: 205) archy.scan_config -> archy.graph (line: 25) archy.simulate -> archy.graph (line: 46) archy.watcher -> archy.graph (line: 35) archy.watcher -> archy.index (line: 36)

$ uvx archy score .

archy score: 0.636 (0.639 before the edit)

modularity: 0.670 (48 communities, raw Q=0.505) call-weighted Q=0.699 (calls amplify community structure) acyclicity: 0.927 (1 cycles, tangle=0.073) depth: 0.533 (max depth 7) equality: 0.411 (Gini=0.589) complexity: 0.767 (2888 functions, cc_mean=2.86, cc_max=46)

graph: 164 modules, 319 edges (318 before the edit)

propagation_cost: 0.1089 (diagnostic, not in score; MacCormack reverse-reach fraction)

calls: 1842 resolved across 262 edge(s), 7.03/edge (diagnostic, not in score)

One import, one edge. A forbidden layer edge, a twelve-module cycle, and the score down 0.003. 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.

Note the size of the score move. 0.003 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 before treating the composite as a quality gate.

That 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 is a one-co