Godfile decomposition: making change possible

A file can become too important to change

An agent system accumulates responsibilities quickly: routing, credentials, retries, persistence, tools, adapters, and lifecycle behavior. When they gather in one module, a small request can require understanding a very large part of the system. The cost of finding a safe boundary rises. Adding another branch looks easier than extracting a coherent responsibility, so the next change makes the eventual extraction harder.

My godfile work addresses that cycle. The aim is to make the system legible enough to change with evidence. Smaller files are an observable consequence; explicit responsibilities and preserved behavior are the engineering objective. The code campaign in All Gods Must Die develops this through a measurable size law, graph-based decomposition, independently checked extraction, and a permanent record of unfinished work. Failure mode and law, p. 22.

Size identifies pressure; responsibility identifies boundaries

The campaign’s 2K Law sets a 2,000-line ceiling for repository code, with the publication’s stated exclusions for non-code documents and vendored trees. It also establishes a tracked migration state for existing oversized files. The law makes the problem enumerable rather than leaving it to whoever happens to open a large module next. Law and enforcement, pp. 22–23, 27.

The threshold is a project discipline, not a discovered universal optimum. The paper explicitly says its value lies in enforceability and acknowledges that the numerical boundary is a choice. Being below the bar does not prove a module has one responsibility: the paper’s platform discussion calls for decomposition of under-ceiling adapters when they still carry several responsibilities. Headroom and threshold qualification, pp. 17 and 32.

Scholarly context: decomposition is a choice of criteria

David Parnas’s 1972 paper treats modularization as a way to improve flexibility and comprehensibility and argues that its effectiveness depends on the criteria used to divide the system. That is a useful context for this work: splitting a file at arbitrary line counts does not establish good modules. My campaign combines size enforcement with analysis of cohesive responsibilities, shared state, consumers, and cross-boundary dependencies. The connection is explanatory; Parnas did not prescribe my 2,000-line rule or this campaign method. Parnas, 1972, original paper and abstract; my cluster-analysis method, p. 25.

The first result was a more honest inventory

The paper’s August 5, 2026 baseline enumerated 119 code files above the threshold. Only 20 were previously tracked as formal campaign targets; 99 were newly exposed by the enforcement walk. These are historical measurements from the publication, not a claim about today’s default branch. Baseline inventory, pp. 23–24.

Source area	Oversized files reported	What this tells a reader
hermes_cli	22	Concentrated command-line responsibilities
gateway	13	Significant pressure in gateway code
tests	15	Verification code also requires decomposition
agent	15	Core agent responsibilities in the inventory
tools	18	Tool-facing code contributes its own burden
plugins	10	Extension surfaces are part of the same maintenance problem
Repository root	4	A few top-level modules can be especially large
apps	8	Application surfaces remain in scope
Remaining directories	14	The problem extends beyond the largest named groups

An inventory visualization should make this distribution visible without turning it into a ranking of people or a claim that every listed file was fixed. The 20/99 distinction is especially revealing: the initial campaign map covered only part of the measured problem. Enumeration changed the available architecture decisions.

The publication reports 553,314 lines above the bar, using that label in its baseline table. That historical aggregate should retain its original definition and date. It is not a count of lines I removed, an estimate of defects, or an independently re-measured current repository statistic. Table 3, p. 23.

Model the seam before moving the body

A safe extraction starts with a graph of definitions and consumers. Which functions share state? Which names are imported elsewhere? Which attributes do tests patch? Which functions are called only during an error path? Which neighboring PR is already changing the candidate window?

My published method has independent regional analysts and adversarial witnesses build that account before adjudication selects a slice. It favors a coherent leaf cluster with limited outside dependencies and makes overlapping work a first-class constraint. The result is a contract naming the source window, destination module, byte evidence, execution order, and blocked alternatives. Method, pp. 25–26.

This preparation protects other contributors as well as runtime behavior. An extraction can be correct in isolation yet impose avoidable conflicts on someone implementing a fix in the same region. File overlap and issue/PR interlocks let the campaign expose that dependency before it consumes another person’s work. The architecture chapter discusses this wider relationship between design, ownership, and execution.

What a byte-preserving move proves

The method records a SHA-256 hash of the selected source window at a pinned commit. After relocation, that evidence establishes whether the moved body is unchanged, with any specifically sanctioned seam edits separately documented and reviewed. A hash comparison makes a narrow, reproducible claim about bytes. Extraction, p. 26.

The crucial qualification is that unchanged text does not imply an unchanged whole program. My paper includes an explicit correction of the stronger wording. Module initialization, name resolution, imports, patch targets, introspection, serialization, and side effects can change at the seam even when the body is preserved. The refined claim is byte-verbatim relocation with residual risk at that seam. Claim 7, p. 54.

An illustrative proof structure is:

Transformation evidence = preserved body + verified seam + exercised behavior + independent review.

This expression summarizes separate obligations. It is not a theorem of whole-program equivalence. A successful hash check cannot prove an import order safe; a passing unit test cannot prove a behavior it never exercises. That precision makes the result more useful to a maintainer deciding whether to accept a change.

Follow one dependency through the move

Consider an illustrative collector function that calls a helper from its module’s globals. Before extraction, a test patches the helper in the original module. After extraction, the collector may look up that helper in its new module. Re-exporting the collector under its old name can preserve the visible import while the patch now changes an object the collector never reads.

This is the failure class documented in the paper’s web-server extraction: an apparently successful test could become ineffective because the patched name no longer sat on the execution path. The fix must address the lookup seam, not merely preserve a familiar public spelling. Recorded defect, p. 30.

Technical context: names are resolved in an environment

Python’s execution model distinguishes source text from the namespace in which names resolve. A module has its own global namespace; a function’s global lookups use its defining module’s namespace. Python’s mocking documentation consequently explains that a patch must affect the location where the tested code looks up the object. These language rules clarify why relocation can change a test’s meaning. Python execution model · Python unittest.mock: where to patch.

The campaign’s seam tests assert identity through the original namespace, then pair that check with behavioral cases and review. Identity is necessary for the specific re-export contract; it is not a substitute for checking globals, initialization, and side effects. That distinction is the reason the evidence must be layered.

A small diff can have several failure modes

The paper’s defect ledger is more informative than a generic assurance that extraction was tested. It records an import-time circularity caused by eager attribute access, an extracted module missing an aiohttp global on an error path, and a re-export that exposed four names when the agreed contract specified three. In each case, the critical risk lived around the relocation rather than in a rewritten algorithm. Defects and catching stages, pp. 30, 58.

Obligation	Evidence that addresses it	What it does not establish alone
Preserve the selected body	Hash comparison against the pinned window	Safe initialization or complete behavior equivalence
Preserve the public seam	Object-identity checks through the original namespace	Every indirect lookup and external consumer
Exercise relevant behavior	Existing tests plus targeted seam/error-path cases	Behavior outside the exercised conditions
Preserve the agreed scope	Diff review against the slice contract	Correctness of an unexamined contract
Respect concurrent work	Current overlap census and explicit coordination	Future changes after the census
Preserve the campaign record	Individually linked PRs, issues, credit, and ledger	Whether maintainers have merged the work

This is where 5×2×3 and rigorous code review join the decomposition story. Review asks whether the evidence reaches the real seam, while mechanical checks establish the propositions they can actually decide.

Keep debt visible while migration proceeds

An existing codebase cannot be described honestly by pretending its new rule was always satisfied. The publication’s manifest records oversized files and baseline sizes, rejects untracked violations, and prevents tracked entries from growing. Its purpose is to make migration measurable while giving future changes an executable constraint. Enforcement, pp. 27–28.

The interesting state change is therefore more than “large” to “small.” A file can be measured, tracked, analyzed, divided into agreed slices, represented by reviewed PRs, and eventually integrated. Different artifacts establish those different states. Conflating them would erase either completed contribution or remaining release work.

As of August 6, 2026, the paper reported 8 of 20 tracked godfiles at its defined SHIPPED stage, with a ninth partially complete. In that edition, SHIPPED explicitly meant completed, reviewed, individually linked open PRs at campaign level. It did not mean merged into a released product. Results, p. 29; definition and limitation, pp. 24 and 33.

A note on the historical slice totals

The paper’s prose and appendix describe 68 open, individually linked PRs, while Table 4’s slice entries sum to 70. These are inconsistent totals in the published edition. This chapter preserves the original and does not silently choose one as a reconciled total. The dated eight-of-twenty status statement can be discussed separately from that unresolved accounting difference. A current project total should come from a fresh, deduplicated repository census.

Architecture becomes durable through evidence

The long-term value of this work is the ability to make the next change with a smaller reasoning burden and a clearer responsibility boundary. It also leaves a trail: why a slice was selected, which seam was preserved, who reviewed it, whose work it intersects, and which acceptance conditions were exercised.

That trail is part of the architecture. My interlocks deliberately connect the former whole, the decomposition problem, the individual changes, and their evidence. Readers can explore those records through the Hermes network and return to the full paper for the original argument. The graph makes a campaign understandable at a scale where reading PRs one by one loses the relationships that give them meaning.

Sources and reading

1. Ibiza, Axl, MBA. (2026). All Gods Must Die: Adversarially Verified Transformation. August 2026, 68 pages. Inventory: pp. 22–24; method: pp. 24–27; enforcement: pp. 27–28; historical outcomes and objections: pp. 29–34; refined claim: p. 54; ledger: p. 58. Read onsite · Original PDF.
2. Parnas, D. L. (1972). On the criteria to be used in decomposing systems into modules. Communications of the ACM, 15(12), 1053–1058. Original paper record and abstract · DOI: 10.1145/361598.361623. Context for decomposition criteria, not evidence of this campaign’s outcomes.
3. Python Software Foundation. Python language reference: execution model. Name resolution. Technical context for the namespace effects of relocation.
4. Python Software Foundation. Python standard library: unittest.mock. Where to patch. Technical context for tests that patch a dependency.
5. NousResearch/hermes-agent, issue #78647. Campaign coordination record cited in the August publication. Original public issue. Current issue state may differ from the historical edition.