The Blind Witness Engine

1. The Blind Witness Engine#

I created the 2K Law and the Blind Witness Engine to make large, agent-assisted changes inspectable without asking anyone to trust the agent that made them. The law limits the accumulation of code in a single file. The engine separates discovery, implementation, verification, and acceptance. Together, they turn “the agent says it is done” into a set of claims another person can reproduce and reject.

My paper, All Gods Must Die: Adversarially Verified Transformation, develops this architecture through two campaigns on Nous Research’s Hermes Agent: decomposing oversized code files and keeping translated documentation faithful to its English source. This course teaches the complete system behind those campaigns. “Blind Witness Engine” names that system here; it is not a claim that the paper announced a separately installed product.

The central problem is easy to recognize. An agent changes a large module, runs some tests, and produces a persuasive explanation of why nothing important changed. Another agent reads that explanation and agrees. You now have two favorable statements, but perhaps only one investigation. The second agent may have inherited the first agent’s boundary, assumptions, omissions, and expected conclusion.

I want the second investigation to exist before it encounters the first answer. I also want something neither agent can persuade: a pinned byte comparison, an identity assertion, a deterministic graph check, a failing test. Independent reasoning and mechanical verification have different jobs. The architecture needs both.

Source: paper §§1.1–1.3, pp. 7–8; §§2.4–2.5, pp. 10–11; synthesis §23, pp. 52–53. Read the definition.

A transformation needs an acceptance contract#

A transformation takes an existing artifact and produces a changed artifact. Moving functions between Python modules is one transformation. Translating a security policy into French is another. Each preserves something while changing something else.

For extraction, the moved body should remain byte-identical while its location changes. For localization, prose should change while commands, identifiers, references, structure, and operational meaning survive. Before asking an agent to produce either result, specify what is allowed to change, what must remain invariant, and who has authority to decide.

Definition 1 in the paper sets four conditions. The producer does not certify its output. An independently authored, information-isolated verifier accepts or rejects it. Acceptance requires that verifier’s verdict rather than the producer’s self-report. A third party can reproduce the verdict from the public artifacts.

Notice what this excludes. A summary is not an acceptance contract. A screenshot of a green terminal is not a complete proof of which source was tested. A second model repeating the implementer’s explanation is not independent analysis. A private assertion that cannot be checked is not a public receipt.

How to use this course#

The course follows the work from authority and inventory through extraction, documentation germination, and adoption. Read the exact role geometry before assigning agents. Read the seam chapter before moving code. Read the semantic boundary before calling a translation complete.

The code fragments and miniature scenarios are illustrative teaching examples, not newly executed campaign receipts. Commands reproduced from the paper are identified as historical interface examples. Historical measurements retain their August 2026 scope. This page does not claim that an open PR was merged, that a particular release incorporated the work, or that the examples below have been run in your checkout.

You do not need to begin as a campaign architect. You do need to distinguish a proposal from a verdict, a file from the graph around it, and a claim about preserved bytes from a claim about runtime behavior. Those distinctions will do most of the work.

2. Five laws, with consequences#

The five laws are my architecture’s operating commitments:

No system component may accumulate authority without becoming legible.

No claim may outrank its evidence.

No actor may certify itself.

No rule counts until it executes.

No debt gets to hide behind institutional forgetting.

They are not five motivational sentences attached to a development process. Each requires a mechanism that can disagree with the person or model doing the work.

Source: paper §1.3, pp. 7–8; shared architecture and authority assignment, §23, pp. 52–53. Declaration · Authority table.

Legibility is a prerequisite for authority#

A gateway module can acquire responsibility for credentials, routing, retries, session state, and platform behavior without anyone explicitly deciding that one file should own all of them. The result has authority because other components depend on it, not because its architecture is understood.

The first law demands a map. Which definitions exist? Which globals do they read? Which callers import them? Which tests replace their names? Which other work is changing the same windows? A line count reveals concentration. A dependency and consumer graph reveals the consequences of moving it.

The same problem exists in documentation. A translated README tells a user how to operate the product. That is authority. If its commands and security instructions no longer match the canonical document, fluent prose can carry an incorrect operational contract. The technical graph makes that authority inspectable.

Evidence sets the width of a claim#

A matching hash proves equality of the bytes selected for hashing. It does not prove that the right window was selected, that an import cycle is impossible, or that a function still sees the same globals. A passing identifier-presence check proves that an identifier is present. It does not prove that the sentence around it retained its negation.

This is why I teach evidence boundaries before tools. If you cannot state what a check fails to establish, you are likely to use its success as permission to claim too much. The appropriate response is not to discard the check. It is to attach the other checks the larger claim requires.

Production and acceptance are separate powers#

The producer can propose an extraction or translation. The pipeline can preserve structure and accelerate production. The deterministic verifier can accept or reject the properties it checks. A blind reviewer or native-language semantic witness supplies an independent quality judgment. CI enforces the accepted rules on subsequent changes.

The paper assigns CI release authority. That does not mean CI presses a maintainer’s merge button or decides editorial meaning. It means the release process must obey the executable gates rather than treating them as optional advice.

Rules and memory must survive the meeting#

“Please keep files small” depends on someone remembering the request. A repository walk that fails when a new oversized source file appears does not. “Please update translations” depends on an editor noticing drift. A parity check against the current English source notices on every run.

Existing debt needs a different mechanism from new violations. A manifest records known oversized files and prevents growth. A status tier keeps legacy translation defects visible as warnings while enforcing errors for fully germinated locales. These are migration contracts, not exemptions from accountability.

Exercise: identify the missing authority#

An agent translates a security policy, asks the same model to rate the result, and reports “excellent.” A separate check confirms that every command block matches. Can the translation ship as germinated?

Answer: not on that evidence. The independent structural check establishes an important part of technical parity, but the producer’s self-rating supplies no independent semantic authority. The remaining graph classes must pass, and a separate semantic witness must inspect meaning. A translation that changes “must not” to “may” can retain every command block. The two kinds of acceptance cannot stand in for each other.

3. Why Hermes needs defenses inside her own work#

I describe Hermes as a female cyborg in the paper. That is an architectural personification, not a claim of consciousness. The useful distinction is between the model’s ability to propose and the surrounding system’s ability to constrain, remember, inspect, and refuse.

Hermes is not merely a string sent to an LLM. The paper describes persistent bounded memory, profiles, sessions, skills, tools, provider routing and fallback, scheduled execution, delegation, and several entry surfaces. An agent with those capabilities can change more than its answer. It can change files, invoke subprocesses, carry information across boundaries, and modify procedures that later work will load.

That is why I place verification inside the surfaces where the agent operates. A defense outside the system cannot compensate for every unsafe assumption inside its tool registry, environment loader, documentation, or review process.

Source: paper §§2.1–2.6, pp. 8–11; §§3.1–3.2, pp. 12–15. System model · Hardening mechanisms.

Follow a value to the place it can escape#

The security series in the paper is a practical lesson in choosing the unit of analysis. A secret is not safe merely because a function named “scrub secrets” exists. Follow the value from its source to each sink: status output, logs, tool results, provider-bound context, cache files, and child-process environments.

The encrypted-cache work removed the plaintext storage branch rather than merely changing a default. Disabling encryption meant memory-only operation; legacy plaintext was migrated and removed. That is a state-transition property. The relevant question is what happens to both new writes and old files, not whether the settings screen says encryption is enabled.

The emission work distinguished recognizable credential shapes from opaque values. A value can be sensitive without beginning with a familiar vendor prefix. The provider-egress work carried applied-secret provenance so a credential did not become harmless merely because it arrived under a name such as FOO.

The child-process work followed the same distinction. Scrubbing a known key name was insufficient when external secrets could be renamed. A sanitized environment builder was also insufficient if a later env.update(os.environ) reintroduced the values. The paper traces sibling paths through terminal factories, a compute host, language servers, plugin sidecars, and a separate shell.exec route. Each was a real place where an apparently centralized defense could be bypassed.

These are historical mechanisms documented in the paper, not a fresh assessment of every present Hermes execution path. Their teaching value is the failure trace: source, transformation, boundary, consumer, missing protection.

Platform claims must reach the platform#

On Windows, a POSIX-looking mode such as 0o600 does not by itself establish owner-only ACLs. The paper’s Windows work used icacls and covered the branch that preserved an existing file’s mode during replacement. A test that examines only first creation can miss a later credential rotation reopening access.

The desktop-auth series likewise checked a real lifecycle. A stale environment-file token could override a freshly injected desktop token. Provenance diagnostics made the source visible without printing the token; a bounded retry avoided turning a short mismatch into a prolonged lockout; a real subprocess regression checked which token the server actually accepted.

The file-safety work protected Git-managed state inside a real .git directory. A file-write tool should not treat repository control data as ordinary project content merely because both occupy the same directory tree. Here, the relevant boundary is ownership and consequence, not a superficial “inside the workspace” test.

Sometimes the correct output is no patch#

One audit in the paper examined the credential-read surface and concluded that an existing migration already covered it. The contribution was a verified no-bypass result, not a newly invented code change.

This matters to the Blind Witness Engine. If every lane is rewarded only for producing a patch, agents have an incentive to manufacture work. An analysis can close an uncertainty. A rejection can prevent a regression. An audit can establish that a proposed fix is unnecessary. Those artifacts belong in the record with their authors and scope intact.

Distributed witnesses are part of the defense#

The code campaign distributes uncertainty across independent regional analyses, adversarial witnesses, adjudication, and fresh reviewers. The documentation campaign distributes authority across the translator, structural gate, semantic witness, and CI. Neither arrangement claims that the model has become incapable of error.

Instead, the system makes a local error less likely to become an unquestioned global decision. A witness can expose a test that no longer exercises the seam. A gate can expose a missing command in otherwise elegant French. A ledger can expose a sibling path nobody owns.

This is the sovereignty argument in the paper: users should retain agency over models, context, tools, execution, and technical records. An inspectable system can show what it changed and why acceptance was justified. A self-certifying system asks the user to surrender that judgment to the same process that produced the result.

4. The 2K Law and the ratchet against hidden debt#

The 2K Law is exact: no repository code file may exceed 2,000 lines. The paper’s stated exceptions are non-code documents—such as Markdown, JSON, YAML, lockfiles, LLMS.TXT, and LLMS-FULL.TXT—and vendored third-party trees. The enforcement walk also excludes virtual environments and build artifacts from the repository’s own source surface.

These exclusions identify what is being governed. They are not permission to rename executable source as documentation, hide first-party code under a vendor directory, or stop walking a difficult part of the tree.

Source: paper §§5.1–5.3, pp. 22–24; §7.1, p. 27; §9.5, p. 32; Appendix C, pp. 58–59. The law · Executable enforcement.

Why the ceiling is hard#

A large file becomes harder to change because its responsibilities are difficult to separate. The easiest short-term edit is then to add another branch inside the same file. That makes the next extraction harder. The file’s size is both a consequence of the cycle and a measurable place to interrupt it.

I chose a strict ceiling, not a scientifically optimal constant. The paper explicitly rejects the claim that 2,000 is a universal optimum. Its value is that it can be enforced without reopening a negotiation every time someone wants to add “just one more” responsibility.

Being under the ceiling does not certify good architecture. A smaller adapter may still mix unrelated lifecycles, state ownership, formatting, and network behavior. The paper calls for a headroom decomposition lane in that situation. The ceiling is a limit, not a target to fill.

Nor does the law endorse arbitrary chopping. Dividing a file into several equally sized pieces while preserving every hidden dependency simply distributes the confusion. Responsibility, shared state, consumers, and initialization order determine the extraction boundaries. The count tells us where concentration must stop; analysis tells us how to make it stop safely.

Establish the census before celebrating progress#

At the paper’s August 5, 2026 baseline, the enforcement walk found 119 files above the threshold. Twenty were already tracked as campaign targets; ninety-nine were not. The first important result was therefore a correction to the campaign’s own map.

A selected list of notorious files is not an inventory. If the enforcement walk omits tests, plugins, or a root-level source file, its clean result describes the walk, not the repository. Before treating the count as debt, document the source extensions, exclusions, roots, and counting method. Another person must be able to reproduce the population.

The paper also reports a large aggregate line quantity. It is a historical inventory measure, not net code deleted. Extraction relocates code; the method does not become more successful by confusing relocation with deletion. This course uses the baseline to explain enumerability rather than turning an ambiguous aggregate into a new performance headline.

Existing violations enter a migration state#

This chapter teaches the paper’s specified contract. The historical implementation and later repository ratchets must be checked separately; Exhibit A identifies the original test’s narrower growth predicate and its actual integration status.

The Pantheon manifest records oversized files and their measured baselines. Its two enforcement obligations are straightforward:

1. An over-ceiling first-party source file cannot remain unmanifested.
2. A manifested file cannot grow beyond its recorded allowance; completed kills leave the debt manifest through the campaign’s verified shipping process.

The manifest is not a permanent waiver. It makes existing violations visible while the campaign removes them. The intended terminal state is an empty debt manifest and continuing enforcement against new oversized files.

Here is an illustrative application of the rule. Suppose an existing module is recorded above the ceiling. A proposed feature increases it again. The feature does not become acceptable because the file was already large: the growth violates its frozen debt allowance. A separate untracked module crossing the ceiling fails for a different reason. A safe extraction that brings a target below the bar must still satisfy its agreed decomposition and shipping obligations; the line count alone does not certify completion.

A ratchet needs an honest ledger#

A ratchet prevents backward movement. Its bookkeeping must not let a team increase a baseline every time a file grows, erase an outstanding target, or remove a row merely to silence CI. Those actions would preserve the appearance of enforcement while surrendering its effect.

The paper binds manifest removal to the kill’s shipping receipt. That receipt includes reviewed slices and public interlock, not just a smaller working-tree file. The campaign ledger and the release tree are different surfaces: the paper’s SHIPPED definition counts completed, linked PR work, not an assertion that maintainers have merged it. Keep that distinction visible when adapting the manifest to your own integration process.

Exercise: what does a clean count prove?#

A scanner reports no new oversized files, but its root list excludes the plugin tree. Can you report that the repository obeys the law?

Answer: no. You can report what the configured scanner inspected. To make the repository-wide claim, reconcile the source surface and its justified exclusions, include first-party plugin code, and rerun the census. A manifest cannot govern files its enforcement machinery never sees.

5. The exact 5 × 2 × 3 method#

The notation is not a multiplication exercise and not a license to invent a convenient number of agents. The paper specifies a concrete information flow:

five regional analysts → five independent adversarial witnesses → five regional adjudicators → one blind implementer per agreed slice → two new blind reviewers per slice.

The first two groups form five mutually blind analytical pairs. The final implementer and reviewer stages repeat as the agreed slices are produced. Fix lanes are added when review rejects a candidate. The method therefore does not mean a fixed total of thirty interchangeable runs.

Source: paper §6, pp. 24–27; cost accounting §8.5, p. 31. Full method · Role counts.

Wave 1: five independent regional analyses#

Partition the godfile into five line-range regions and give each analyst a pinned, read-only worktree at the same consensus commit. Each reads its complete region. A regional boundary divides reading work; it does not declare that definitions on opposite sides are independent.

Every analyst must produce six artifacts: an AST inventory, a cluster and dependency map, a consumer census, a first-extraction recommendation with an exact window, the window’s golden SHA-256 computed before movement, and a live census of overlapping open PRs. Chapter 6 explains what makes each useful.

The paper also imposes a write-first gate: after reading, the analyst writes an analysis deliverable larger than 10 KB before further verification. The file is durable evidence when a model route throttles or a completion message is lost. This is not a demand for padded prose. An oversized empty report still fails substantive review.

Wave 2: replicate without inheriting the answer#

Five fresh adversarial witnesses inspect the same five regions. They must not read their Wave-1 counterpart’s output until their own deliverable is written. They independently reconstruct the analysis, including their own hash from the same pin.

Their brief directs attention toward observed failure classes: ineffective tests, import-time crashes, missing globals, incomplete consumer or PR censuses, and missed collisions. They are adversarial toward the claim, not hostile toward the producer.

Blindness here concerns the answer and reasoning, not the specification. Both witnesses need the same source pin and obligations. Giving one witness a different revision would create disagreement about the input, not a useful independent assessment of the same artifact.

Wave 3: adjudicate, implement, challenge again#

One adjudicator per region reads the two completed analyses and re-verifies every load-bearing claim at the pin. The decision is not a majority vote. The paper gives a fixed tiebreak order:

1. Live open-PR overlap: a window touched by an open PR is blocked until that PR lands (land-order coordination), regardless of which witness preferred it. The adjudicator can select a collision-free alternative while that window remains blocked.
2. Zero module-state entanglement: prefer a slice that does not inherit hidden state dependencies.
3. Leafness: prefer the coherent cluster with the fewest outside dependencies.

The resulting consensus contract names the first slice, exact window, destination module, golden hash, execution order, and blocked alternatives. The implementer receives that contract but not the witnesses’ reasoning. It verifies the pin, moves the agreed body, preserves the original public seam, adds identity and behavioral tests, compares failures with the pristine pin, and commits with sign-off without pushing.

Two new reviewers then inspect the committed extraction. One emphasizes correctness; the other emphasizes adversarial failure discovery. They do not know one another’s verdict or the expected answer. Both must approve. Either reviewer’s REQUEST CHANGES sends the slice to a fix lane; the repaired state returns to both reviewers. A previous approval is not automatically approval of a changed commit.

The orchestrator has a deliberately narrow job#

The orchestrator dispatches work, maintains interlock, and keeps the ledger. It does not perform the analysis, extraction, adjudication, or review itself. This prevents the coordinator’s preferred schedule or accumulated narrative from becoming the acceptance authority.

A well-written dispatch can carry the source pin, scope, required artifacts, and forbidden inputs without carrying the desired conclusion. “Verify this candidate against the contract” is appropriate. “The previous lane proved this is safe; confirm it” contaminates the task before inspection begins.

This separation costs compute and coordination. The paper records throttling and exhausted credit, not effortless infinite parallelism. Durable deliverables reduce lost work; they do not erase the cost. Independence is valuable because it can interrupt momentum, and the workflow must budget for the interruption rather than treating rejection as an operational inconvenience.

Exercise: two agents, one investigation#

A witness receives the analyst’s report, rewrites it in different words, checks two cited lines, and independently chooses APPROVED. Does a separate session make this a blind cross-check?

Answer: no. Session separation does not undo information exposure. The witness inherited the prior answer before producing its own account. Preserve the contaminated report as a record if useful, but obtain the required independent analysis without presenting that report as the blind counterpart. The gate is defined by information isolation and evidence, not by the number of chat windows.

6. Six artifacts before the first move#

The regional analysis is not a recommendation with supporting decoration. It is six different views of the same pinned source. Each view catches an omission the others can miss. If a report supplies a compelling cluster diagram but no consumer census, it has not established that the proposed boundary is safe to move.

Source: paper §6.2, p. 25; adjudication §6.4, pp. 25–26; collision findings §8.3, p. 30. Required artifacts.

The AST inventory tells us what exists#

An abstract syntax tree identifies definitions from language structure rather than from a search for lines beginning with def. The inventory records every top-level definition and its exact span. Decorators, multiline signatures, classes, and nested definitions need their proper context; the inventory must not silently turn a method into a top-level function or start a window after a decorator that belongs to it.

Read the region itself as well as generating the inventory. An AST does not explain why a module-level assignment runs before registration, why a compatibility alias exists, or why an apparently unused object is inspected dynamically. The machine provides structure. The analyst is responsible for connecting that structure to the program’s obligations.

The cluster map explains what belongs together#

A cluster groups definitions that share responsibility or state. Its edges show dependencies inside the region and across regional boundaries. A collection of neighboring functions is not automatically a cluster; proximity is a clue, not the criterion.

Consider an illustrative module containing a provider-name formatter, a credential cache, and a function that persists the chosen provider. The formatter may be a leaf if it depends only on arguments and constants. Persistence may look equally small but write module-owned state. Moving the formatter first can reduce risk without pretending that both functions are independent because they occupy adjacent lines.

A useful map records edge direction. “A and B are related” does not tell the adjudicator whether moving A requires B, whether B calls A, or whether both mutate the same object. The extraction order depends on that distinction.

The consumer census follows names outside the file#

List imports, callers, patch targets, re-exports, and other observable uses of the candidate names. Search beyond production code. A test that monkeypatches the original namespace is a consumer of that namespace. A plugin that imports a compatibility alias is a consumer even if its path is outside the main package.

Static search provides evidence, not a completeness theorem for dynamic Python. String-based lookup, registration, reflection, serialization, and plugin loading can hide consumers from an ordinary import scan. Record where the census searched and which dynamic surfaces need a probe. “No grep matches” cannot become “no consumers” without that boundary.

The recommendation identifies an executable slice#

The first-extraction recommendation names a coherent leaf cluster, an exact source window, and a proposed destination. “Move the provider helpers” leaves too much discretion. The implementer should not be discovering which helpers count while it is already editing.

A window must preserve the definitions’ syntax and meaning. If the candidate is noncontiguous or depends on initialization outside the window, expose that fact. Do not manufacture a contiguous-looking slice by omitting inconvenient dependencies. The consensus stage can choose a different first move.

The golden hash binds the proposed bytes#

Compute the SHA-256 of the selected window at the source pin before movement. Record the source path, commit, window convention, and hash together. A digest without those inputs is an opaque string; a line range without a pin points at moving material.

The second witness derives its own digest from the same source. Matching hashes help reveal agreement about the selected body. They do not excuse disagreement about consumers or initialization.

The live PR census protects concurrent work#

The source pin freezes the code being analyzed, not everyone else’s activity. An open PR can touch the chosen window while the campaign is running. The overlap census therefore needs actual changed paths and hunks, not only titles containing the filename.

The adjudicator rechecks this census independently. In the paper, an initial report counted six touching PRs where the live census found twelve; other recommended windows overlapped active changes. A beautiful dependency argument could not override the collision gate.

Exercise: diagnose an incomplete report#

An analyst supplies all definitions, a cluster diagram, a window, a hash, and an open-PR list. It says tests need no inspection because the extraction preserves function bodies. Which required artifact is missing, and why does it matter?

Answer: the external consumer census is incomplete, especially its patch consumers. Preserved function bodies can resolve globals from a different module after relocation. A test patching the old namespace may become ineffective while remaining green. That is a seam risk, not a body-edit risk, and it is exactly why the census exists.

7. Pin the contract, then prove the bytes#

The consensus contract is the boundary between investigation and implementation. It names what the implementer is permitted to do and what it must leave alone. A good contract reduces discretion at the moment discretion is most dangerous: after the actor has begun changing the repository.

Source: paper §6.4, pp. 25–26; refined Claim 7, §24.3, p. 54. Extraction contract · Exact claim boundary.

The contract needs more than a destination filename#

The paper requires the first slice, its exact window, module name, golden hash, execution order, and blocked list. The source pin belongs with that contract. The implementer checks the pin and hash before copying, rather than assuming that its worktree still contains what the analysts inspected.

The blocked list is useful evidence. It explains why an apparently attractive candidate did not advance: an overlapping PR, module-state entanglement, or a dependency that makes it unsuitable as the first slice. Without it, a later actor can unknowingly revive a rejected plan and call it a fresh improvement.

A consensus contract is not a permission slip for adjacent cleanup. Renaming variables, improving error messages, reorganizing conditionals, and changing defaults may be reasonable work. They are not the same claim as a byte-verbatim relocation. Separate them so reviewers can tell which proof applies to which change.

Hash bytes, not a reformatted interpretation#

This illustrative Python fragment shows the basic relationship between a commit, a path, a line window, and a digest. It is an explanation of the paper’s byte gate, not a reproduction of a newly executed extraction:

import hashlib
import subprocess


def pinned_window(repo, pin, path, first_line, last_line):
    body = subprocess.check_output(
        ["git", "-C", repo, "show", f"{pin}:{path}"]
    )
    lines = body.splitlines(keepends=True)
    assert 1 <= first_line <= last_line <= len(lines)
    window = b"".join(lines[first_line - 1:last_line])
    return window, hashlib.sha256(window).hexdigest()

Here the interval is one-based and inclusive. Line endings remain part of the bytes because keepends=True retains them. That convention must match the actual contract; it must not be silently substituted for another campaign’s window definition.

The important point is where the bytes come from. Reading a modified working-tree file after extraction and calling its digest “golden” reverses the proof. The golden value comes from the agreed original. The candidate must answer to it.

When a new module contains imports or a header around the moved body, hashing the whole new file is not the same operation as hashing the selected body. Locate the agreed moved window and compare that content. Do not strip whitespace or normalize line endings to make a mismatch disappear while continuing to call the comparison byte-identical.

Sanctioned seam edits remain visible#

The paper allows documented lazy imports and a pinned seam rewrite, each reviewed as part of the commit. That allowance is narrow. It does not convert “byte-verbatim” into “roughly equivalent after convenient edits.” Separate the preserved body from the sanctioned seam changes and show both to the reviewers.

The original module receives an identity-preserving re-export. The paper’s identity condition is:

getattr(godfile, name) is getattr(module, name)

This checks object identity, not merely equal output for a sample input. Two different functions can return the same value once while exposing different identities, globals, metadata, or patch behavior. Identity is therefore a meaningful seam requirement, but it is not the entire seam proof.

Claim 7 is the claim to teach#

The paper’s refined wording is “Byte-verbatim relocation with seam-bounded residual risk.” The moved body is unaltered by construction when it matches the golden hash. Imports, re-exports, initialization order, patch targets, and callers still require verification.

That refinement matters more than a reassuring headline. A body can be unchanged and the program can still behave differently. The next chapter shows how. The correct response is to make those residual risks explicit and test them, not to pretend a digest proves runtime equivalence.

Compare failures at the pristine pin#

The implementer runs seam tests and the region’s existing tests. If a failure appears, the paper requires proving that any claimed pre-existing failure also occurs at the pristine pin. “This looks unrelated” is not a comparison.

Keep the test selection, environment, and failure evidence comparable. A candidate failure and a baseline success indicate a regression until explained. Two failures with different causes do not establish equivalence merely because both commands exited unsuccessfully. A valid baseline comparison names the same failure and its scope; it does not erase unrelated missing coverage.

8. The seam is where unchanged code can change behavior#

A Python function does not carry only its visible body. It also executes in a context: a globals dictionary, imports, class relationships, initialization history, callers, and public lookup paths. Moving the body changes its address in that context. That is the seam the engine must inspect.

Source: paper §6.4, p. 26; defects §8.3, p. 30; objection §9.3, p. 32; Claim 7, p. 54. Observed seam failures · Refined preservation claim.

Object identity does not preserve every lookup#

Consider this illustrative failure trace. A collector originally lives in old_module and calls a global named fetch. A test patches old_module.fetch and exercises the collector. The collector is moved to new_module; old_module.collect becomes a re-export of the same function object.

The identity assertion can pass:

assert old_module.collect is new_module.collect

But the function now resolves its global fetch in the new defining module. Patching old_module.fetch no longer controls that lookup. The test may still return a plausible value, or its weak assertion may pass without the intended path being exercised.

A behavioral seam test needs to establish the route, not merely the result. For example, an illustrative test sketch can install a sentinel at the supported patch boundary and require the collector to observe it:

seen = []

def sentinel_fetch():
    seen.append("patched boundary reached")
    return "sentinel-result"

monkeypatch.setattr(old_module, "fetch", sentinel_fetch)
assert old_module.collect() == "sentinel-result"
assert seen == ["patched boundary reached"]

The sketch assumes that preserving this old patch boundary is part of the contract. It is not a generic fix to paste into every project. The implementation must actually route through the required boundary, or the contract must explicitly describe and review a different compatibility decision. Changing the test to patch the new module without examining the old promise can hide the regression.

Imports have timing, not just names#

A lazy lookup works because it delays resolution until the required object exists. Calling that lookup at module scope makes it eager again. During a circular import, one module can observe another before initialization has finished and crash while accessing an attribute that would exist later.

A “module imports successfully” test run only after other tests have warmed sys.modules may miss the problem. Fresh-process or controlled import-order probes are useful ways to examine this risk. They should exercise the actual import route rather than only importing the new module in the one order that happens to work.

The paper records this class directly: eager access to a late attribute at module scope produced an import-time circularity. The moved algorithm was not the source of the crash. The new initialization relationship was.

Free names can survive compilation and fail at runtime#

A function can refer to aiohttp without the destination module importing it. Python can compile that function. The missing name becomes a failure only when execution reaches the reference, which may be an error branch rather than the happy path.

For every moved definition, inspect names that are not local arguments or locally bound variables. Determine whether they come from imports, constants, mutable module state, registration, or another definition. The destination must receive the required binding without accidentally copying state that should remain shared.

Copying a dictionary to “make the name available” can introduce a different bug: two modules now own diverging state. An import that captures a value once can differ from a lookup that observes later updates. The consumer and dependency maps must distinguish object sharing from mere spelling.

MRO, introspection, and serialization are seam questions too#

The paper’s refined claim names initialization, name resolution, introspection, serialization, and side effects as residual concerns. A useful teaching extension is to apply that reasoning to a class extraction: inspect the method resolution order, or MRO, whenever a proposed move changes inheritance relationships.

Moving methods into a mixin can change which implementation super() reaches, which class owns a descriptor, and which method wins when several bases define the same name. An identical method body does not establish an identical class composition. Such a change may exceed a pure relocation contract and need to be blocked or specified separately.

Likewise, code that depends on __module__, a qualified import path, pickling, reflection, or a registry key may observe relocation. These are not additional historical defects attributed to the paper’s seven-item ledger. They are practical ways to investigate the seam risks Claim 7 explicitly preserves.

Do not leave orphans behind the new module#

An extraction can create several kinds of orphan. An old public name can disappear while a caller still imports it. A test can remain in the tree after its patch no longer reaches execution. A registration side effect can remain in a module that nobody imports. A moved helper can exist without any live caller because its old call site was missed.

Check the graph in both directions. From each promised public name, follow resolution into the new implementation. From each moved definition, identify its consumers and required state. From each relevant test, identify the behavior it actually observes. A file’s existence is not proof that it participates in the running program.

Exercise: the three green checks#

The moved window matches its hash. The old and new exported functions are identical objects. The happy-path unit test passes. An error path references a library available only in the old module. Is the extraction accepted?

Answer: no. Each green check establishes a narrower property. None creates the missing destination global. Exercise the error branch, establish the correct import or late-bound dependency under the consensus contract, then return the changed candidate to both reviewers. Hash equality is preserved-body evidence; it cannot repair the seam around that body.

9. Seven defect classes, with the right witnesses credited#

The defect ledger is more useful than a claim that “multiple agents reviewed the code.” It names failures, identifies who caught them, and shows which earlier process did not. It also demands careful attribution: four catches belong to pass B; two belong to consensus-stage checking; one belongs to direct repository verification.

The paper’s abstract and some summary language compress these into a broader second-witness claim. The detailed ledger is more precise, and that is the account I teach here.

Source: paper §8.3, pp. 29–30; Appendix B, p. 58. Detailed catch sequence · Defect ledger.

1. A silent monkeypatch no-op#

The extracted web-server collector resolved a function through the new module’s globals. A test patched the original module and therefore no longer controlled the executed lookup. Pass B caught this after pass A and the implementer had approved.

The lesson is not “add another test count.” It is “verify that the test still reaches its intended seam.” A green test can be a verification illusion when relocation changes what its patch intercepts.

2. Eager late-attribute access#

A lookup intended to resolve an attribute late was invoked during module initialization, producing a circular import crash. Pass B caught the issue after earlier approval.

The name of a helper does not establish when it executes. Trace the call into module scope, then examine import order. “We use lazy imports” is a design claim; the actual execution point decides whether the property exists.

3. A missing aiohttp global#

An extracted Slack mixin referenced aiohttp without importing it in the destination module. The affected error path would raise NameError. Pass B caught this after both pass A and implementer self-review had approved.

This is why the dependency inventory must include free names and failure branches. A successful compile and an exercised normal path leave that branch untested.

4. A re-export beyond the consensus#

In the main.py extraction, the implementer exported four names where the consensus allowed three. The extra export exposed cluster-private state. Pass B rejected the deviation after pass A had approved it.

Even an apparently harmless extra name changes the public surface. An implementer cannot enlarge the contract because exposing one more object seems convenient. Review must compare the actual namespace with the agreed namespace, not merely confirm that the requested names are present.

5. An open-PR census undercount#

A witness reported six open PRs touching the auxiliary-client file. The consensus adjudicator’s independent census found twelve. This was an adjudication catch, not a pass-B extraction-review catch.

The failure concerns the population supporting a coordination decision. If the census is incomplete, a “collision-free” conclusion may be unsupported before a single line moves. Recounting the live surface is part of adjudication, not administrative work to postpone until shipping.

6. Live in-window collisions#

Several recommended auxiliary-client windows overlapped hunks in open PRs that the initial census missed. The consensus live gate found the collisions, demoted those windows, and selected alternatives.

The tiebreak order did real work here. A favored leaf slice did not advance merely because it was structurally appealing. The live overlap rule took precedence and converted a hidden merge-order conflict into a visible blocked candidate.

7. A propagated false precedent#

A claim about a large file’s reduction and PR count had spread across seventeen issue bodies. Direct repository verification established that the precedent was false, and the correction addressed the repeated class rather than only the first occurrence.

This is citation rot inside the campaign’s own coordination layer. A repeated assertion does not gain evidentiary weight by appearing in more issue bodies. When those bodies derive from one unsupported statement, they are copies of one error, not independent receipts.

What the ledger establishes#

The four pass-B examples establish that an independent adversarial review rejected concrete candidates that earlier review had accepted. The other examples establish the value of independent adjudication and direct verification elsewhere in the system. Together they demonstrate that uncertainty must be checked at more than one stage.

They do not establish a universal detection rate, a causal effect size, or the number of defects a different team would catch. There was no randomized control group in this campaign. Treating seven defect classes as seven independently measured improvements in reviewer accuracy would exceed the evidence.

Exercise: write the accurate result#

A report says, “The second reviewer caught all seven bugs, proving that double review eliminates extraction defects.” Repair it.

Answer: “The published ledger records four pass-B catches after earlier approval, two consensus-stage census or collision catches, and one direct-verification correction of a false precedent. These cases support the workflow’s feasibility and show concrete failure modes it intercepted. They do not prove elimination of defects or a general detection rate.”

10. Interlock and the meaning of SHIPPED#

A correct patch can still be an incomplete campaign artifact. If its issue does not name it, its EPIC does not track it, its sibling work conflicts with it, or its contributor disappears from the record, the campaign cannot explain what it has done.

I call the required binding interlock. It is a bidirectional work graph, not a related-links footer.

Source: paper §3.3, pp. 15–16; §5.4, p. 24; §6.5, pp. 26–27; §7.3, p. 28; §9.6, p. 33; appendices A/G, pp. 58, 61. Interlock definition · SHIPPED standard.

Bind the graph in both directions#

The paper requires five kinds of relationship. A PR binds the relevant issue. The issue thread names the PR. Related PRs identify sibling surfaces, collisions, and merge order. The EPIC maintains the current table of members, owners, dependencies, status, and evidence. Credit remains attached to the artifact.

A source-derived example of the paper’s campaign binding is:

Part of #78647
Part of #78631

These lines illustrate the published campaign convention; they are not messages posted by this course. Part of is recognized by the campaign audit. Do not confuse that convention with GitHub’s native automatic-closing keywords. In particular, using Fixes on a campaign meta-issue risks closing the whole umbrella when only one slice lands.

The reverse edge is equally important. The issue thread needs the literal PR token, and the EPIC needs an individual link for every slice. A PR range makes the reader infer membership; an enumerated roster makes membership auditable. Progress on #N or a loose Related footer does not satisfy the paper’s binding contract.

Deduplicate before claiming ownership#

Interlock begins before a new PR exists. Search the relevant issues and open work, inspect the manifest, and identify existing owners. If another contributor has already supplied a seed or a partial fix, the campaign should preserve and extend that work rather than create an uncredited duplicate.

I require the audit to check PR-to-issue links, issue-to-PR links, duplicate work, and resolution convergence, with any hole in any direction causing failure. That is the paper’s interlock contract, not a claim that every historical implementation enforced it completely. A coordination gate needs tests just as a parser does: otherwise its definition of “linked” can drift while its output remains reassuring.

The historical audit has offline regression fixtures, but its PASS is not a complete certificate of that contract. At the inspected pin, unbound_prs is recorded but omitted from the final HOLES predicate, and a closed, unmerged binding PR can be counted as convergence because the computed set of open PRs is not used there. Its live collector is also bounded rather than exhaustive. Exhibit A gives the exact limits.

The paper also records a practical authority limit. Some remaining gaps belonged to contributor-owned PR bodies the campaign could not edit. Those gaps were recorded with the exact action required, not silently declared closed. “Zero holes in the directions we control” is different from “the entire graph has no holes.”

A KILL LOCK preserves the former whole#

The permanent campaign record connects the old godfile, the issues that described its problems, the shard table, and the roster of fixing PRs. That allows future work to locate the new responsible module instead of resurrecting the old concentration because its history is easier to find.

The lock is not merely a prohibition. It supplies navigation. A future contributor needs to know where the behavior went, which seam remains public, and which debt has already been retired. Without that map, a size ceiling can prevent one kind of growth while leaving everyone to rediscover the architecture.

SHIPPED is not merged#

The paper defines a godfile as SHIPPED when every slice of the agreed decomposition has been extracted, blind-reviewed to agreement, and delivered as individually linked open PRs. This is campaign completion at the PR level. It is not a claim that the default branch or a released package contains the changes.

Maintainers control merge decisions. The campaign controls whether its work is complete, reviewable, and interlocked. Keep both facts in the ledger. A candidate may be campaign-shipped and still awaiting integration; a merged change can still need a release. Neither distinction reduces the value of completed work. It prevents a status word from promising a different artifact.

The historical paper reports eight tracked godfiles at its SHIPPED stage, but its prose aggregate of PRs and its table total differ. I do not reconcile that discrepancy by inventing a new exact aggregate. Individual artifact links and the stated status definition are the safer evidence boundary.

Exercise: what remains after code review?#

A slice has two approvals and passing local tests. Its PR names the shard issue, but the issue thread has no PR token and the EPIC still shows “analysis.” Is it campaign-complete?

Answer: no. The reverse edge and ledger state are missing. Repair the exact issue and EPIC relationships, verify them, and preserve the test and review receipts. Then report the actual state—open PR, merged, or released—without replacing one with another.

11. Documentation is a graph of operational promises#

A translated README can read beautifully and still teach a different product. It can omit a command, retain a retired symbol, lose a security path, or send the reader to an anchor that no longer exists. The problem is not visible if the only acceptance question is whether the French sounds fluent.

I designed germination to protect the load-bearing structure of documentation while allowing its language to change. The English root documents become the comparison source. The locale documents are transformations whose technical obligations must remain inspectable.

Source: paper §§11–13, pp. 34–39; parent conformance model §21, p. 50. Graph definition · Conformance layers.

Start with a bounded document set#

The paper’s root set is README.md, CONTRIBUTING.md, and SECURITY.md. Their French twins are README.fr.md, CONTRIBUTING.fr.md, and SECURITY.fr.md. A twin is a counterpart with a defined relationship, not simply another document somewhere in the repository.

From each document, the gate extracts fenced code blocks, inline technical spans, link targets, headings, and special navigation edges among the root documents and their twins. Ordinary prose is outside this structural graph. That makes extraction deterministic without pretending the checker understands every sentence.

A fence contributes its marker, language tag, and a hash of its comment-normalized body. A code span contributes the exact identifier it encloses. A link contributes a target. A heading contributes structure and a slug. Hub edges express whether readers can find the locale and return to the canonical English page.

Rewriting is narrow and explicit#

A locale rewrite changes root-document targets to their corresponding twins. CONTRIBUTING.md can become CONTRIBUTING.fr.md. An already localized target must not become CONTRIBUTING.fr.fr.md.

External URLs, mailto: targets, bare fragments, and relative paths outside the root set are fixed points of that rewrite. A translator is not authorized to invent a French version of an arbitrary asset path or external documentation URL. Fragment resolution is checked separately against the target document’s headings.

This matters because naive localization often treats everything that looks English as translatable. A filename is not prose. A command flag is not prose. The visible label of a link can change while its destination remains fixed.

Two different truths need two different checks#

Documentation conformance asks whether a document’s claims resolve against code, configuration, symbols, and assets. Germination asks whether a locale preserves the canonical English document’s technical graph.

Those are separate layers. If English teaches a nonexistent command and French copies it perfectly, cross-language parity can pass while both documents remain wrong about the product. Germination does not replace docs-to-code conformance. It prevents localization from introducing a second, less visible divergence.

Conversely, a locale can contain only valid commands and still omit half the commands English teaches. A docs-to-code check may accept each remaining command while the parity check rejects the missing coverage. The two gates answer different questions.

Structural freedom does not mean semantic freedom#

The paper’s refined Claim 6 is essential: prose is structurally free, not semantically unconstrained. A translation can rearrange words, choose idiomatic phrasing, and explain a concept naturally. It cannot reverse a security warning or remove a condition that changes when an operation is permitted.

Imagine the illustrative instruction “Do not run reset before exporting your configuration.” A translation that drops “not” can preserve the code span reset, every link, and every heading. The structural graph remains intact while the operational meaning becomes dangerous.

That is why a mandatory semantic witness accompanies the mechanical gate. The checker protects extracted structure; the human quality layer examines meaning, including negation, order, compatibility, version qualifications, and security constraints. The engine becomes stronger when those authorities are separate, not when the structural checker claims to replace the language expert.

12. The seven parity gates#

The parity checker returns typed issues with a class, severity, and detail. The seven classes describe different ways a locale can lose the product its source teaches. Treating them as separate classes makes a failure actionable: the translator can repair the missing edge instead of guessing what “translation invalid” means.

Source: paper §15, pp. 41–43; formal definitions, Appendix D, p. 59; comment normalization §14.4, p. 40. Seven classes · Formal contracts.

1. Fence parity preserves operational bytes#

The gate compares the ordered sequence of fence signatures: marker, language, and body hash after comment normalization. An omitted command, reordered block, altered language tag, or changed non-comment byte can fail this class.

Order matters. A document that installs a dependency and then invokes it does not teach the same procedure if its command blocks are reversed. Counting blocks without comparing their ordered signatures would miss that change.

The refined rule allows explanatory comments to be localized while preserving commands, flags, and paths. Line-leading comments other than shebangs and trailing comments are treated as localizable prose under the implemented normalization. Backtick identifiers inside those comments remain protected by span parity.

For example, translating the explanation around env -i should not require translating or deleting the identifier itself. The code stays exact; the comment’s human language can change. The normalizer’s limits still matter, as chapter 13 explains.

2. Code-span parity preserves identifiers#

Every required English backtick span must appear in the locale, either verbatim or in the permitted rewritten form when it names a root document. The span inventory includes prose spans outside fences and protected spans inside fence comments.

This catches a missing environment variable, a translated identifier, a lost source path, or an obsolete symbol. It protects exact strings that a reader may type, search, import, or use to understand a boundary.

The paper’s formal definition is set-based presence. Do not silently upgrade it into a proof of occurrence counts, sentence placement, or explanation quality. One surviving occurrence can satisfy presence even if another important occurrence disappeared. Semantic review and more specialized conformance tests cover questions that presence alone cannot answer.

3. Link-target parity preserves destinations#

External references remain exact. Root-document paths follow the locale rewrite. Other relative assets remain fixed. Bare fragments are deferred to the anchor check rather than compared as untranslated English strings.

Other-locale README links in the English language selector are deliberately exempt from this class. A French README does not need to reproduce every Spanish, Chinese, or Urdu hub link simply because English carries the full selector. Discoverability and return-to-English navigation have their own classes.

A useful illustrative failure is a translated link label with its destination accidentally removed. The sentence can still read naturally; the reader has lost the referenced instructions. The target check sees the missing operational relationship even when the prose remains persuasive.

4. Anchor parity makes navigation resolve#

A fragment such as a section link must resolve against the locale heading slug set, or the appropriate root-document twin when the link names one. Translating a heading without updating its incoming fragment leaves a dangling edge.

The gate therefore needs a slug model aligned with the renderer it is trying to protect. A manually guessed fragment is not evidence that a link works. Punctuation, accents, duplicate titles, and language-specific characters can all make intuition unreliable.

The paper records French trailing-hyphen failures and tests its slug behavior. When adapting the checker to a different renderer, verify that renderer’s behavior rather than treating the paper’s compact implementation as a universal slug specification.

5. Heading parity preserves the outline#

Compare the ordered heading-level sequences. Translating a title is allowed; dropping a section, merging two sections into one, or introducing an extra heading changes the structural fingerprint.

This is stronger than checking the total heading count alone. Two documents can have the same number of headings while nesting them differently. The ordered level sequence protects that shape.

It is still not semantic section matching. Two equally leveled sections can retain the same outline while their content is swapped or mistranslated. The checker’s success remains a structural claim.

6. Backlink parity preserves an escape route#

A locale README must link to exactly README.md, the canonical English root README. Sideways links to other translations do not satisfy this requirement. Neither does a generic link to the project’s website.

A user encountering a confusing translation needs a direct route to the comparison source. This is a user-facing operational edge, not a courtesy footer. It also makes the canonical relationship explicit rather than forcing the reader to infer it from filenames.

7. Discoverability prevents orphan translations#

For a germinated locale, the English README must link to the locale’s README twin. A technically correct file that nobody can find from the project’s front door is incomplete as a delivered localization.

Backlink and discoverability are intentionally separate. One tests the route out of the locale; the other tests the route into it. A one-way relationship can satisfy one and fail the other.

The whole tree has a verdict#

The aggregate check walks the manifest and root-document set, skips pending locales, and reports errors and warnings together. Missing germinated files are errors. Legacy missing files remain visible in the debt reporting rather than being mistaken for complete coverage. CI fails when errors exist; warnings remain printed.

The gate compares against the current English source, not a saved snapshot that can become stale alongside the translation. When English gains a command, a germinated locale must carry that command before parity is restored.

Exercise: choose the responsible class#

A French README has all the commands, identifiers, headings, and references required by English. It links back to English, but English has no language badge or other link to the French file. Which class fails?

Answer: discoverability. The locale’s internal quality does not establish the incoming hub edge. Adding another backlink inside French would not repair the missing English-to-French route.

13. A verifier is only as honest as its parser#

A deterministic gate is not automatically a correct gate. If its parser fails to see a code block, invents an identifier, or miscomputes an anchor, it can reject valid work or accept broken work with perfect repeatability.

The paper records eight failures that became implementation rules. They are part of the architecture because they determine what the verifier can observe.

Source: paper §16, pp. 43–45; extractor contracts §14.5, p. 41; graph extension §24.2, p. 54. Parser failure sequence.

Fence boundaries need state#

A naive regular expression can close a fence when it encounters another triple-backtick sequence with an information string. The remaining code then leaks into the prose scanner, creating phantom spans and headings.

The paper replaces this with a line-based state machine: recognize an opening marker, remain inside the fence, and accept a closing marker only under the closing-line rules. Fence interiors are masked to spaces before other scans, retaining positions and line counts.

This is a targeted GFM-oriented scanner, not proof of complete CommonMark support. When adopting it, test longer fence delimiters, valid closing lengths, indentation, tildes, nesting contexts, and malformed input against the syntax your renderer accepts. Do not label a simplified delimiter rule a complete Markdown parser merely because the campaign’s fixtures pass.

Backticks can invent evidence#

A dangling backtick can cause naive matching to consume a later real pair as a multiline “identifier.” A translation that repairs the authoring error then appears to have dropped a span that never had technical meaning.

The paper’s implementation collects backtick positions on fence-masked text, pairs them globally in order, and drops pairs containing newlines. That is a declared heuristic with regression tests. It is not a universal implementation of every valid Markdown code-span form. Multiple-backtick delimiters and multiline spans require explicit treatment if they matter to an adopter’s corpus.

The lesson is to test both false negatives and false positives. A verifier that blocks good translations with phantom requirements creates pressure to bypass the gate.

Whitespace can defeat a preservation rule#

An indented HTML badge failed a check that only recognized lines beginning directly with <. It became a prose replacement site, allowing a model to rewrite its href. The repair applied lstrip() before the HTML-preservation check.

That failure is small in code and large in consequence. A template’s promise to preserve HTML is only as real as the branch that recognizes HTML in the actual source.

Navigation has several contracts#

Requiring every locale to repeat the entire English language selector over-enforced link parity. The repair exempted other-locale README selector targets while retaining separate backlink and discoverability checks.

Rewriting an already localized target produced a double suffix. The repair left an existing twin unchanged. These cases show why a rewrite should be explicit and narrow rather than a general text substitution.

The French trailing-hyphen anchor issue exposed another boundary: the gate’s slug derivation and the written fragment had to agree. The paper locked French and CJK examples in tests. An adopter still needs renderer conformance, including duplicate-heading behavior and punctuation cases beyond those examples.

Severity belongs to migration policy#

Applying full error severity to every old translation immediately made historical drift block the new gate. Silencing those checks would have made the debt disappear again. The paper instead kept the same observations and changed their consequence through explicit status tiers.

This is not a parser repair, but it belongs in the failure sequence because an unenforceable migration policy can kill an otherwise useful verifier. Legacy debt is reported at warning severity; germinated locales must remain clean.

Comments require a language-aware boundary#

Raw byte hashing blocked legitimate translation of explanatory comments inside command fences. Comment-normalized hashing preserved operational bytes while making comment prose localizable.

That refinement has a limit: a # is not always a comment. It can occur inside a quoted string, URL fragment, or syntax whose comment rules differ from shell. A normalizer that erases meaningful bytes can hide a real command change. Test quoted markers, shebangs, languages without shell-style comments, and backtick identifiers within comments before extending the rule to another corpus.

The public paper presents the implemented normalization and its campaign evidence. It does not establish correct lexical analysis for every programming language. Preserve that boundary rather than generalizing one successful README check into a universal code-equivalence claim.

Exercise: test the checker’s sight#

A fence normalizer removes everything after the first # on every line. It reports equal hashes for two command lines whose quoted strings differ only after that character. What failed?

Answer: the observation model. The checker treated executable string content as a comment and erased the difference before hashing. Add a failing fixture for that syntax, repair or narrow the normalizer, and rerun both clean and corrupted cases. Repeating the hash comparison cannot recover information the normalizer discarded.

14. French: the seed, the gate, and the semantic witness#

French was the first complete germination case, not a disposable demonstration. Contributor iacker supplied a professional French-Canadian seed in PR #63660 for the request in issue #60535. The seed contained the three root documents and a README language badge. It was good prose, and it had drifted from the moving English source.

I directed the work that preserved that seed, built the parity architecture, refreshed French, and separated structural acceptance from semantic review. Preserving iacker’s authorship was part of the engineering, not a note added after the translation had become useful.

Source: paper §17, pp. 45–47; credit §20, pp. 49–50; refined Claim 6, pp. 53–54. French case · Meaning-preservation boundary.

The campaign repaired both content and record#

The French request had been swept into a conformance-umbrella closure claim. But a translation is a content deliverable; the existence of a related conformance effort does not produce the requested French files. The campaign corrected the record, preserved the seed commits through cherry-picking, built a conformance gate, and refreshed the locale against current main.

The architecture and French work were recorded in PR #80391, with the broader language campaign coordinated through EPIC #80392. Those are the paper’s historical artifact references, not a claim about their present merge state.

Eight categories of drift became visible#

The paper records these eight categories in the seed:

1. A README command fence omitted hermes config get.
2. French still described six terminal backends after English had added a seventh, Vercel Sandbox.
3. A CONTRIBUTING test-run fence differed in its explanatory treatment of env -i and per-file isolation.
4. A test-hook reference was stale: the documented symbol no longer matched the current hook.
5. Two French section fragments had trailing hyphens that did not match the gate’s slug model.
6. The security surface description had lost technical paths and identifiers, including plugins/platforms/<name>/ and base.py.
7. A CONTRIBUTING section had been merged, leaving the heading structure out of parity.
8. Required code spans were missing across the three documents.

These are drift categories, not eight interchangeable parser classes. Several can manifest through the same gate. A backend count written only as ordinary prose would not become mechanically protected merely because a similar historical mismatch was caught when its technical listing changed.

The run-tests comment case also belongs to the architecture’s development history. The initial raw-fence comparison exposed a difference; the later comment-normalized rule allowed legitimate comment translation while protecting commands and embedded identifiers. Do not teach the initial strict rule and the refined rule as if they were the same contract.

A structural pass did not finish the language work#

The paper records a blind French semantic-quality pass with 28 findings and zero meaning-changing technical errors on the reviewed material. That is a distinct receipt from the structural gate. Stylistic or idiomatic findings can still improve a translation without changing whether the operational graph passes.

The refined doctrine requires human semantic authority, including native-language review where appropriate. Do not inflate a recorded blind semantic pass into a controlled study of human review quality or an endorsement by every French-speaking user. Its reported scope is the campaign’s reviewed French material.

A semantic witness should inspect instructions with consequences: negation, permission, ordering, limits, version conditions, compatibility, and security warnings. Merely reading for elegance misses the precise meanings that a graph-preserving mistranslation can reverse.

The automatic path had a real historical proof#

The campaign also ran a real model through a Windows-safe Python stdin/stdout wrapper into a scratch output directory. The paper reports a 19,434-character French README that passed the gate, with no residual English prose phrases on the checked surface.

That proves the automatic path completed in the reported experiment. It does not mean every future model invocation will pass, that every English phrase is always detected, or that a structural pass eliminates semantic review. The mocked failure tests and human editing path remain important because generation is not deterministic.

Exercise: preserve the contributor and the boundary#

You update an older translation substantially. Can you replace its provenance with “generated by the new pipeline” because the final file differs from the seed?

Answer: no. Preserve the seed’s contribution and identify the refresh separately. Git authorship, manifest provenance, contributor mapping, the PR body, and the campaign ledger should explain the lineage. The pipeline’s later work does not erase the person who supplied the original translation, and the seed’s quality does not exempt the refreshed file from current-source checks.

15. Germination as a maintained workflow#

The pipeline has four principal actions: extract, template, germinate, and check. It also exposes a status view. These actions separate the source model, production aid, generation step, and acceptance verdict instead of hiding them inside one persuasive model response.

Source: paper §14, pp. 39–41; §§18–20, pp. 48–50; appendices E/F/H, pp. 59–61. Pipeline actions · CLI surface.

Extract and template before generation#

extract emits the English document’s technical inventory as JSON. The inventory makes required fences, spans, links, and headings visible before anyone translates.

template preserves technical structures and marks prose for translation. It keeps fenced bodies, HTML and badge lines, table structure, and heading positions. For README templates, it injects the English return link. This reduces avoidable generation errors, but the gate still re-extracts the result; a template is an aid, not an acceptance oracle.

The following commands reproduce the paper’s interface examples. They are historical source commands, not commands executed for this course. They presuppose a checkout containing the published implementation:

python scripts/docs_germination.py extract --doc README.md --locale fr
python scripts/docs_germination.py template --doc README.md --locale fr
python scripts/docs_germination.py check

Generate outside the deterministic checker#

germinate sends a constrained prompt and template to a configured command through stdin/stdout, writes the locale output, and checks it. The paper’s example generator command is:

python scripts/docs_germination.py germinate --locale fr --doc README.md \
  --llm "hermes chat -Q -q"

This is the paper’s command spelling, not a claim that the same CLI syntax is current in every Hermes installation. The continuation shown is shell syntax. The historical Windows implementation used native C:/... paths and a Python wrapper; native Windows subprocesses did not accept MSYS paths or a shell script as an interchangeable executable.

The model’s output can be rejected. Its subprocess can fail. The product therefore includes mocked tests for a clean write-and-pass result, a drifted result that must be rejected, and a generator failure that must surface loudly. Those tests run without a model or network connection.

The human route remains first-class: template, edit by hand, run the same check, obtain semantic review. Automatic generation accelerates production; it does not own acceptance.

Three statuses make migration possible#

A locale does not become germinated because a model produced three files. The files must be substantive, not verbatim English copies, structurally clean, linked from the hub, and accompanied by the required semantic acceptance and provenance.

A manual locale is not silently excluded. Its warning debt is printed on every check. The paper’s August 6 snapshot reported zero errors and 35 warnings across the campaign tree, while Spanish CONTRIBUTING alone lacked 173 required spans. Those figures count different things: aggregated warning records are not the same population as missing identifiers. Preserve the distinction when reporting debt.

The manifest is also a roadmap and credit ledger#

The manifest records locale name, native name, badge information, status, provenance, and notes. Its language ordering used the paper’s cited speaker-population source, with an additional next-in-line entry. That is a declared prioritization choice, not a claim that global speaker counts perfectly represent developer needs.

Notes preserve in-flight contributor work so another lane does not duplicate it. Right-to-left locales require layout review beyond graph parity. Website localization is another surface; root Markdown parity does not certify the whole documentation site.

The conformance tests import the pipeline’s implementation rather than maintaining a second version of slugification, rewriting, or parity. That avoids two implementations disagreeing about what “pass” means. It does not remove the need for independent expected outcomes and corrupted fixtures that can expose a shared implementation defect.

Exercise: a green build with visible debt#

A manual locale produces warnings while a germinated locale passes. Is the green aggregate build a claim that every locale is correct?

Answer: no. It means no error-severity obligations failed under the declared migration policy. The manual locale’s debt remains visible and needs an owner and roadmap. Changing its status to suppress warnings would hide debt; promoting it to germinated without completing the work would misstate the acceptance contract.

16. Feature parity is not pretending platforms are identical#

A multi-platform agent cannot make Telegram, Discord, Slack, WhatsApp, a desktop app, and a provider API identical. They expose different primitives, lifecycle rules, permissions, and failure modes. Alignment means measuring each against an explicit capability contract and preserving those differences in the result.

The same witness architecture applies: establish what the external platform permits, inspect what the implementation actually does, compare the documentation’s claims, and reconcile existing work before filing another issue.

Source: paper §3.4, pp. 16–17; documentation conformance §21, p. 50. Feature-parity campaign.

Begin with reconnaissance, not a feature-name checklist#

The paper’s recon gathers issue labels and searches, open PRs, adapter size at the source pin, official API documentation, and deduplication anchors. A method called send_message does not establish parity for threading, media, authorization, retry semantics, or group policy.

Write the campaign model before filing the EPIC: why the work exists, its lanes, hard standards, deliverables, and ledger shape. Pin a worktree for each lane to a common base. Classify every relevant open issue, including unresolved triage rows, and expose dependencies. An unclassified issue is still part of the population; omitting it makes the ledger look more complete than it is.

Wave 1 produces blind gap catalogs. Wave 2 independently cross-checks them without inheriting the first answer. Wave 3 validates against current main before filing and interlocking the confirmed gaps. A finding can be correct at the analysis pin and obsolete by publication. The current-main check prevents a campaign from filing yesterday’s already-fixed defect as today’s new work.

Use the five gap classes precisely#

The label is a classification, not the evidence. Attach the official requirement, the inspected implementation path, the observed consequence, and the issue or PR that owns the work. If the evidence does not support a final class, retain the triage state rather than making the row disappear.

An oversized adapter gets a decomposition lane. An under-ceiling adapter with several responsibilities can get a headroom lane. Feature work and structural work must coordinate: a gap implementer should not add another responsibility to a window another lane is extracting without an explicit order.

Exercise: distinguish a missing feature from a duplicate#

A blind analyst discovers that a platform’s retry behavior is incomplete. An existing issue already describes the same failure, and an open PR changes the same path. Should the campaign file a new “unsupported retries” issue?

Answer: not on that evidence. Inspect the existing record, classify the tracked defect, bind the owning PR, and record any genuinely uncovered remainder. Independent discovery does not create a second defect. The campaign’s contribution can be validation, a missing reproduction, or corrected scope without duplicating ownership.

17. Skills, attribution, and durable procedural knowledge#

The engine must preserve more than source code. Agents load instructions that shape later work. A bloated or contradictory skill can become an authority surface as difficult to inspect as the godfile it tells the agent to refactor.

The paper therefore applies progressive disclosure to skills: keep the loaded core legible and move branch-specific detail into references that are loaded when needed. This is structural decomposition of operational context, not deletion of knowledge.

Source: paper §§3.5–3.6, pp. 17–18; §7.2, pp. 27–28; §20, pp. 49–50. Skill architecture and credit.

Keep the map separate from the reference library#

The campaign’s skill-body bar was 500 lines and 60 KB. Known-large skills had frozen measured sizes; disclosure violations were enumerable and expected to shrink. The core skill carried triggers, invariants, routing, and completion criteria. Reference files carried recipes, detailed examples, and less frequently needed branches.

This is not a claim that every model should receive only a short prompt. It is a loading decision. A procedure needed for one platform should not consume every unrelated session’s context. A critical invariant should not be buried in a reference nobody is told to load.

Refactoring a skill also needs conformance. If it documents a command, test that the command surface exists. If it routes to a reference, ensure that the reference is present and still says what the core promises. A shorter file with broken routing is not an improvement.

Preserve who contributed what#

Attribution is part of the evidence graph. A later maintainer needs to know who supplied a seed, who repaired it, who wrote the rejection fixture, and who challenged a false completeness claim. That history supports revisiting and repairing the system.

In the French campaign, the original commit author survived cherry-picking; provenance named the seed; contributor mapping associated the authored work with its recognized identity. In security work, an acceptance test and a no-bypass audit received credit even when neither looked like a new feature.

My authorship of the doctrine does not erase those contributions. Agents generated, inspected, implemented, and verified under my direction. Contributors retain their own authored artifacts. The record should distinguish those forms of work without pretending that directing an engineering system is less real than typing every line manually.

Exercise: a reference move that loses the rule#

A skill is shortened by moving its failure-handling section to a reference. The core file no longer tells an agent when to load that reference. Its line-count check passes. Is the refactor complete?

Answer: no. The rule has become harder to reach at the moment it matters. Preserve the trigger and routing in the core, then verify the reference link and the documented behavior. The count measures loading cost; it does not prove that the procedure remains operationally complete.

18. Measure what the engine proves#

The paper is a case study, not a universal theorem about multi-agent reliability. Its strength is that it specifies a repeatable mechanism and exposes concrete artifacts, failures, corrections, and limitations. The right evaluation preserves those boundaries instead of translating every favorable observation into a larger claim.

Source: paper §§4, 8–10, pp. 19–21, 29–34; §§24–26, pp. 53–57; availability statement, p. 62. Objections · Parity experiment.

Agreement is a gate, not a probability of truth#

The paper draws on inter-rater reliability, blinded experimental design, refactoring research, LLM-as-judge work, and code-review literature. It does not report a chance-corrected agreement coefficient for its reviewer population. Its agreement condition is binary: the required witnesses agree, or the candidate does not advance.

Independent information paths reduce opportunities for anchoring, but they do not eliminate correlated model errors. Two witnesses from the same model family can miss the same defect. A shared mistaken interpretation can also influence which tests they consider sufficient.

Mechanical gates complement that judgment. They do not make the residual risk disappear. A byte comparison cannot be persuaded by a flattering summary, but it can still compare the wrong window if the contract is wrong. A test can execute deterministically while asserting too little. The seven recorded defect classes are directional evidence of intercepted failures, not a controlled estimate of the method’s effect size.

The parity experiment has a precise denominator#

At the paper’s germination pin, 41a78cd3a8353686b7a38a99ed63fb9ed921e7c4, the evaluation injected one drift per gate class into the French material. All seven expected classes were detected after verifying that the mutations actually changed their targets. The clean comparison used three shipped French documents and produced no error findings.

That is 7/7 seeded class detections and 0/3 clean-file error cases, not proof of perfect accuracy on arbitrary Markdown or every locale. The runtime figures—3.08 ms mean for a README pair over fifty iterations and 20.7 ms for the manifest check—belong to the paper’s Windows 11, Python 3.11 measurement. They are not benchmarks newly run for this page.

The initial mutation attempt reported 43% recall because some intended corruptions did not land as expected. One URL survived elsewhere; a targeted fragment was absent. The corrected experiment used extracted targets and verified text changes before judging detection.

That is a general measurement lesson: first prove that the challenge was introduced. A detector cannot miss a mutation that never happened, and a test harness cannot claim coverage merely because it attempted a replacement.

What remains outside these receipts#

Both campaigns concern one repository and a narrow operating context. The paper reports one model-family campaign, not a controlled cross-model comparison. Semantic review was not measured across all locales. Right-to-left layout and website localization remain separate obligations. The 2,000-line boundary is a deliberate policy choice, not an empirical optimum.

The parser protects the graph it extracts, not every possible meaning in Markdown. Additional protected categories—tables, alt text, version qualifications, shell-output expectations, and security-sensitive prose—are possible extensions, not capabilities established by the original seven classes.

The implementation history also needs its own evidence. A paper can specify a strict ratchet while a particular historical test implements a narrower predicate. The Hermes case study separates my published doctrine, the original contribution, later repository mechanisms, and dated review evidence. None should be silently substituted for another.

Exercise: report a failed challenge honestly#

You intend to remove a required external link, run the gate, and see no error. Inspection shows another copy of the same target remains in a badge. What can you conclude?

Answer: the intended absence was not established. You cannot yet call this a false negative. Define the tested property, remove all relevant occurrences for that presence-based check, verify the changed input, and run the gate again. If you instead want occurrence-sensitive coverage, that is a different contract and requires a different test.

19. Adopt the complete workflow#

Adoption begins by defining a transformation the engine can actually verify. Do not begin with an agent count or an impressive dashboard. Begin with the artifact, its source of truth, its allowed changes, and the evidence that can reject a bad result.

The sequence below applies the paper’s complete workflow to a new repository. It is an adoption guide, not a report that these steps have already been executed on your project.

Source: paper §§5–7, pp. 22–28; §§14–20, pp. 39–50; authority assignment §23, pp. 52–53. Code workflow · Documentation workflow.

Establish the baseline and the work graph#

First, identify the governed source surface and exclusions. Run the inventory, record the pin and counting convention, and enumerate existing debt. Reconcile open issues and PRs before assigning a new owner. Preserve contributor provenance from the beginning.

Write the campaign model and maintain an EPIC with actual rows: artifact, owner, dependency, state, evidence, and next acceptance condition. This is where a reader should discover blocked work and unresolved triage, not only completed slices.

Install the executable policy at the appropriate layer. For source size, distinguish the terminal ceiling from the legacy-growth ratchet. For documentation, distinguish germinated obligations from manual debt and pending roadmap entries. Verify the reject path with a controlled violation; a gate that has only passed a clean tree has not demonstrated refusal.

Run the code transformation without collapsing roles#

Partition the target into five regions at a common pin. Dispatch the five analysts with the six-artifact contract and durable write-first requirement. Dispatch five fresh witnesses without their counterparts’ outputs. Keep their information boundaries intact until the independent deliverables exist.

Give each region’s pair to its adjudicator. Recheck claims and live PR overlap, then apply the fixed tiebreak order. Publish the consensus contract and blocked alternatives. If the pin changes, reconcile the contract against the new source; do not reuse a digest as if it referred to different bytes.

An implementer moves each agreed slice in a fresh worktree, preserves the public seam, adds identity and behavioral coverage, checks baseline failures, and commits without pushing. Two new blind reviewers inspect that committed state. Rejection routes to a fix lane, followed by both reviewers checking the repaired candidate.

Only after the gates open does the authorized shipping step create the PR and update both directions of interlock. Record the candidate’s actual integration state. CI enforces the accepted rules as the repository continues changing.

Run documentation through both acceptance layers#

Define the root set and locale manifest. Extract the current English graph, prepare the template, and produce the locale by human editing, model generation, or both. Run all seven checks and repair the reported drift without weakening the source contract.

Then obtain independent semantic review. Have the witness examine material instructions, not just style. Apply repairs and rerun the structural gate because an editorial correction can accidentally alter a command or link.

Verify all required files, the incoming hub link, the English backlink, and provenance. Promote the locale only when the structural and semantic obligations are satisfied. Keep legacy warning debt visible and assign the next migration work rather than claiming the whole language roadmap is complete.

Leave enough evidence for someone else to disagree#

A code handoff should let another person identify the pin, window, digest, sanctioned seam edits, tests, two review verdicts, collisions, and PR relationships. A documentation handoff should expose the source revision, locale files, typed gate results, semantic review, manifest status, and credit lineage.

Preserve failed attempts and repair decisions when they explain acceptance. A final “all good” summary without the rejected state can hide the exact failure class the engine learned to catch. The point is not to retain every irrelevant log forever; it is to retain the evidence needed to reconstruct the decision.

20. Capstone: refuse the wrong green result#

The following combined scenario is illustrative. It is designed to test whether you can apply the architecture when several plausible success signals arrive together.

A team extracts a provider cluster from a large module. The moved body matches its golden hash, the new module is below the ceiling, and local tests are green. The implementer adds one extra public re-export because a future feature may need it. One reviewer approves. The second reviewer reads the first verdict before starting and also approves.

At the same time, a French security document passes every structural parity class. A sentence changes “only after approval” to “before approval.” The locale is marked germinated because the model rated its translation highly. The PR links the campaign EPIC, but neither the shard issue nor the language issue names it. The EPIC records “released.”

Source principles: paper §§6–7, pp. 25–28; §15, pp. 41–43; Claims 6–7, p. 54; SHIPPED limitation §9.6, p. 33. Authority and refined claims.

Question 1: what actually passed?#

Answer: the selected moved body matched the agreed bytes, a destination file met the size limit, the invoked local tests returned success, and the locale passed the implemented structural checks. Those are useful results. None should be discarded merely because other obligations failed.

But they do not establish namespace fidelity, independent review agreement, semantic preservation, complete interlock, merge, or release. The correct report names the narrow successes without letting them absorb the missing evidence.

Question 2: where must the code candidate stop?#

Answer: the extra re-export violates the consensus contract. Remove it or obtain an explicitly revised contract through the proper adjudication path; do not let the implementer enlarge the public surface unilaterally. The second review is not blind because it encountered the prior verdict first. A valid fresh review is still needed.

Inspect the seam as well as the export list. Confirm module globals, import order, old patch routes, and actual consumers. Green local tests do not prove those obligations were exercised. Any repaired commit returns to the required reviewers; approval attaches to a candidate, not to a branch name forever.

Question 3: why did the documentation gate miss the reversal?#

Answer: the changed timing condition lived in ordinary prose outside the extracted graph. The checker did not claim to understand that condition. The missing authority is the semantic witness, not another favorable rating from the producer.

Repair the instruction, obtain independent semantic acceptance, and rerun the structural checks after editing. A legitimate semantic repair can still accidentally damage a code span or fragment, so the two gates should converge on the same final document.

Question 4: what state can the ledger honestly record?#

Answer: not released, not merged, and not campaign-complete. The candidate still lacks required independent acceptance and reverse issue bindings. Record the actual work and blockers. Once the artifact, review, and interlock obligations are complete, the paper’s SHIPPED status may apply to its individually linked open PRs. A release claim requires separate release evidence.

The transferable judgment#

The engine’s value is not that it creates more opportunities to say yes. It creates precise reasons to say no, precise routes to repair, and a record that explains why a later yes is justified.

That is the work I want a reader to be able to reproduce: expose the authority, identify the invariant, isolate the witnesses, execute the check, preserve the contributor, and leave the remaining debt visible. The evidence is allowed to interrupt the schedule. The producer is not allowed to overrule it.

21. Hermes Exhibit A#

Hermes is the production case study for the architecture I authored: the 2K Law, graph-gated transformation, independent witnesses, seam verification, and an interlocked record of what is complete and what remains. I built the doctrine and directed the campaigns; agents performed analysis, implementation, and verification under that direction. The public record also preserves other contributors’ work and later implementation decisions.

This exhibit follows that record from the August campaign into later simplification and review. Its repository observations were checked on October 14, 2026, approximately 18:04–18:14 UTC. Historical counts belong to their named commits or publications. They are not permanent telemetry, and this chapter is not a new full review of the present Hermes tree.

Methodological source: paper §§6–9, pp. 24–33; authority and limitations, §§23–26, pp. 52–57. Paper’s evidence boundaries. The dated primary sources below supplement, rather than replace, that specification.

August: authorship, distributed work, and a durable record#

I opened EPIC #78647 on August 4, 2026. It is the public coordination object for the godfile campaign: the former wholes, shard work, dependencies, attribution, and completion conditions belong together there.

My August 5 account describes “Seventy-two lanes at the peak, roughly 730 lane-dispatches across the night.” That is my published operational account: a peak of 72 lanes and approximately 730 dispatches over the night, not 730 simultaneously active workers. The source review for this exhibit recovered the article; it did not independently reconstruct every historical dispatch from worker telemetry.

The distinction matters because scale is not the method’s acceptance condition. Dispatching more agents does not establish more independent evidence if they inherit the same answer or fail to leave usable artifacts. The architecture’s durable unit is the verified deliverable and its relationship to a pinned source, not the number of workers a coordinator says it launched.

The canonical paper later corrected a propagated precedent used in that older account. I do not carry the corrected engineering numbers forward merely because the earlier article is mine. The paper’s detailed defect ledger and refined Claim 7 govern the teaching here.

August 6: the historical implementation is inspectable#

The enforcement implementation is attached to the verified commit 458473cc6c60770b1eccf3c56e90bba1e2043664, authored under andrexibiza and committed August 6. Its subject is “test(skills): enforce 2K law, progressive disclosure, and KILL LOCK audit with pytest.”

The contribution in PR #79779 contains real code, not only a doctrine document. Its final pinned 2K test stores 119 manifest entries in a Python dictionary and counts physical lines over a selected source surface.

The exact implementation must be described more narrowly than its comments. The growth assertion reads:

assert n <= recorded + 5

That historical test permits five lines above the stored value. It does not mechanically enforce the paper’s stricter zero-growth statement. Missing manifest paths are skipped; the module does not independently compare the manifest against a protected earlier revision or prove that a removed entry corresponds to a shipped kill. The separate interlock audit and the witness protocol address different obligations. A line-count test cannot certify them by implication.

I apply the same distinction to the interlock audit at 5daff1e2166b57fbf153eb26505b1b217d898161. It records PRs with no keyword binding in unbound_prs, but leaves that list out of the final HOLES predicate. It computes an open-PR set named shipped and then does not use it for convergence: any binding PR counts, including one that is closed and unmerged. Its collector requests at most 200 issues and 100 PRs, fetches comments for only the first 50 shard issues, and does not paginate those comments. A PASS from this historical script therefore does not certify the full bidirectional interlock and SHIPPED contract I require in chapter 10.

As of the observation date, #79779 was closed and unmerged, following an October 2 closure. Its code remains inspectable at its pin; that is not evidence that this exact suite landed on upstream main. The distinction preserves both my implementation contribution and the actual integration history.

Seam identity was concrete, not just a phrase#

The historical Telegram contribution, PR #79010, supplies a particularly clear example. Its descriptor-aware seam test checks that the adapter inherits the mixin, moved methods are absent from the adapter’s own dictionary, and those names exist in the mixin.

It then compares plain functions by identity, classmethods through their underlying __func__, and staticmethods through the unwrapped function. That is the mechanism behind the MRO discussion in chapter 8. It establishes the declared resolution relationship, not universal runtime equivalence.

This PR was also closed unmerged at the October 14 observation. The source was inspected for this exhibit; those historical tests were not rerun here. An inspectable implementation, an executed test receipt, and an upstream merge are different facts.

September and October: the release says what became smaller#

The Hermes v0.22.0 release uses the exact phrase “a codebase a third smaller.” Its displayed release date is October 13; GitHub records publication on October 14 UTC. That is a real release statement, and it is worth reading alongside the implementation that supports it.

The linked whole-codebase simplification PR #102117, authored by teknium1 and merged September 4, describes structural decomposition, helper unification, dispatch tables, and dead-code removal. It also reports comment and docstring compaction. Its headline source metric is 1,063,826 → 698,363 lines for non-test Python files across directories, not an independently reproduced all-language census in this exhibit.

My byte-verbatim extraction contract preserves moved bodies. It cannot, by itself, explain that entire net reduction. The later simplification has its own authors, mechanisms, verification narrative, and credit; the release highlight credits @alt-glitch. The release’s “zero behavior change” language is its reported claim, not a universal guarantee newly proven by this page.

My EPIC explicitly recognizes Teknium’s simplification as the structural predecessor for its continuation. It also retains eight residual source-owner tasks and distinguishes the historical twenty-file campaign’s contributor-defined completion from repository-wide completion. This is how an engineering history can credit substantial progress without making remaining debt disappear.

October 8: a 507-row ledger tied to one head#

My October 8 review of PR #106742 is pinned to e86e5ae117a9b9963fb459aefbddbcb8370b2c32. The retained review body contains 507 data rows across 44 Markdown tables, excluding table headers and separators: 35 current-head rows and 472 reconciliation rows.

That is a verification and reconciliation ledger, not 507 unique bugs, 507 passing tests, or 507 fixes. Its statuses include open findings, partial work, historical closure, corroboration, retested closure, and unverified boundaries. Original reviewers remain credited in the reconciliation.

The review states the distinction directly:

Historic closure means the reviewer/author reported a repair at an earlier head; current behavior is unverified unless retested below.

It also separates GitHub’s thread-resolution flags from defect status and warns that overlapping test runs do not sum. Packaged-platform, authorization, UI, upgrade, and hostile-input boundaries were not all exercised. The ledger’s scale matters because it preserves those distinctions rather than compressing them into a single green total.

The scheduler shows why a ratchet is not the ceiling#

In the same large gateway/session-runtime PR, my October 8 inline finding identified cron/scheduler.py growing beyond an already oversized baseline. The pinned source recounts support this sequence:

At the first reviewed head, the file grew against its named base. At the later observed head, it was smaller than that base but still above 2,000 lines. Satisfying a growth ratchet is progress; it is not completion of the hard-ceiling obligation. This is structural evidence, not a runtime defect deduced from file size.

The repository’s later code-health configuration at 311155fade43d1993ea968909a2ad36762345bbc specifies blocking enforcement and a FILE_LINES target of 2000. It is a distinct mechanism from the August embedded manifest. Configuration inspection does not establish that every runtime entry point invokes it, nor that every oversized file is gone. At observation, #106742 remained open and unmerged; recounting one file was not a fresh full-PR acceptance review.

Dated source ledger#

This record shows the doctrine in use: authorship preserved, work made legible, claims bound to exact artifacts, and unfinished responsibility left visible. The same standard applies to my own implementation and my own historical account. That is how the architecture remains inspectable after the campaign that produced it.

22. Use the standalone 2K Law enforcer#

The architecture now has a distinct implementation under my own namespace: andrexibiza/2k-law. The code in that repository is my original work. It contains no copied or vendored Hermes Agent code; the links to my earlier Hermes contributions document my authorship, not an imported code dependency. It provides a Python CLI and a GitHub Action for the size ceiling and legacy burndown, with separate exact-byte and Python Seam Identity checks. This is the executable starting point for the adoption workflow in chapter 19.

The package does not dispatch the Blind Witness Engine for you. It supplies mechanical checks that the engine can use. Choosing coherent boundaries, obtaining independent analysis, checking behavior, preserving contributor credit, and maintaining the campaign’s work graph remain responsibilities of the people and agents doing the transformation.

Implementation source: the public repository, its test suite, and provenance record. Methodological source: paper §§5–7 and refined Claim 7, §24.3. The original size-law contract. The commands below target the standalone package, not the placement-coupled historical Hermes test file.

Install a real package, not a pasted test#

The requirements are Python 3.11 or newer and Git. The package has no runtime dependencies beyond the Python standard library. Its current version is 0.1.2.

git clone https://github.com/andrexibiza/2k-law.git
cd 2k-law
python -m pip install .
2k-law --version

A virtual environment keeps the installation separate from other projects. On Windows, a path such as C:/projects/example can replace the example target path. If a shell does not find the installed console command, the same interpreter can run python -I -m two_k_law. The isolated form also avoids importing a lookalike package from the current directory.

For reproducible automation, the installation can name an exact reviewed commit:

python -m pip install "git+https://github.com/andrexibiza/2k-law.git@FULL_REVIEWED_COMMIT_SHA"

That final token is deliberately a placeholder for the actual commit selected from the repository, not a fabricated SHA or a PyPI availability claim. The version tag v0.1.2 identifies this release. The repository’s commit history and CI records expose the implementation behind the name.

First check: the ceiling without an exemption#

python -I -m two_k_law check --root /path/to/project

The command emits JSON. A complete clean scan exits zero with status: "pass". A measured violation exits one. Invalid input or an incomplete observation exits two; a failed read is not converted into a green empty inventory.

The scanner counts physical lines, including comments and blank lines. LF, CRLF, and lone CR each delimit records; a final line without a terminator still counts. Exactly 2,000 lines is permitted. The JSON records source paths, measured counts, raw-byte hashes, exclusions and reasons, remaining debt, and findings.

The rejection path is reproducible without experimenting on an important project. The following creates a new disposable demonstration directory; it refuses to reuse an existing directory with that name:

python -c "from pathlib import Path; p=Path('2k-law-demo'); p.mkdir(); (p/'legacy.py').write_bytes(b'# example\n'*2001)"
python -I -m two_k_law check --root 2k-law-demo

The second command is expected to exit 1 and report the oversized source. That refusal is the point of the exercise. It does not mean installation failed. The committed smoke test exercises the same progression—initial rejection, explicit baseline adoption, rejection of growth, and retirement at the ceiling—through real installed CLI subprocesses.

Adopt measured debt explicitly#

For an existing repository, baseline prints a proposed manifest:

python -I -m two_k_law baseline --root /path/to/project

It does not write into the repository or grant its own proposal authority. The output has the shape:

{"version": 1, "limit": 2000, "files": {"legacy.py": 2001}}

This example describes the disposable file above. Actual projects receive their own measured paths and counts. An accepted proposal belongs at the target repository’s root as .2k-law.json, committed alongside the exact source it describes. Review of that adoption commit establishes the initial accepted state.

A subsequent comparison names that full accepted commit:

python -I -m two_k_law check --root /path/to/project --base FULL_ACCEPTED_BASE_COMMIT_SHA

The checker reads the previous source and previous manifest from Git objects. For that comparison, --root must identify the Git repository’s top-level directory; an unrelated nested directory cannot borrow its parent’s allowances. An edited candidate manifest cannot legalize one extra line, invent an allowance for a new oversized file, or transfer another file’s unused budget. Each surviving oversized path must stay at or below its previous measured count. Current manifest values must match the current measurement exactly; compliant or deleted files leave the ledger.

The distinction is visible in the result. pass_with_debt is not ceiling compliance. It means the complete comparison passed while named oversized files remain. The result reports those files and their excess lines. A repository with no remaining oversized source can report pass and ceiling_compliant: true.

After a shrink, another baseline invocation can produce the updated ledger. The next accepted change must use that latest accepted state as its base. Continuing to compare forever against the original adoption commit would permit growth back toward the original size; a trusted-base workflow is part of the contract, not an administrative detail.

Put the check in GitHub Actions#

The Action is a thin adapter over the same engine. For a pull request in a repository with accepted legacy debt:

name: 2K Law
on: [pull_request]
permissions:
  contents: read
jobs:
  ratchet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false
      - uses: andrexibiza/2k-law@v0.1.2
        with:
          base: ${{ github.event.pull_request.base.sha }}

The base objects must be available locally. For supply-chain pinning, the Action’s tag can be replaced by its reviewed full commit SHA. A repository with no oversized legacy debt can omit base and use the strict ceiling check.

The Action passes its inputs as data and never installs the inspected project or runs runtime seam imports. The workflow and required check still need trustworthy ownership. A tool cannot protect its own authority if a candidate can replace the checker, select an arbitrary old base, or remove the required job. Nor does a historical passing run establish that a newer head was tested.

Check bytes and identity separately#

The bytes command compares a declared source window from an immutable Git commit against the moved file:

python -I -m two_k_law bytes --root /path/to/project --base FULL_SOURCE_COMMIT_SHA --source original.py --start 20 --end 40 --target extracted.py --target-start 5

Line windows are inclusive and one-based. Both SHA-256 values appear in the result. Line-ending changes fail equality; no normalization silently weakens the claim. The check establishes equality of that selected window—not that the window was the right architectural choice.

Python runtime identity has a separate seam command and a JSON specification. An object check compares the original and moved function or class. An inherited-member check also requires the declared mixin to own the method in the actual MRO, rejects direct shadowing, and distinguishes functions, staticmethods, classmethods and properties.

python -I -m two_k_law seam --root /path/to/project --spec seams.json --allow-execution

That command executes the target’s imports with the caller’s privileges. It is not a sandbox. It refuses without the explicit acknowledgement and is not invoked by the ordinary Action. Its specification examples show the supported forms.

The remaining behavioral questions do not disappear when identity passes. Does patching the original module intercept the actual call? Does initialization still succeed? Does super() retain its intended meaning? Those are the application-owned regression cases and independent review obligations taught in the preceding chapters.

A small enforcer, with an explicit boundary#

Version 0.1.2 uses a fixed, versioned inventory policy. It counts unknown nonbinary text conservatively, accounts for excluded documentation and assets, and refuses observed unsafe source links, unsupported modes and incomplete reads. Root build/dependency/vendor directories must really represent those categories; filename policy cannot infer semantic ownership. The checker assumes a quiescent working tree and does not claim containment against a hostile concurrent writer.

The README documents source scope, resource limits, unsupported encodings, explicit adoption, and the trust placed in Git and Python. The committed tests and CI make the supported behavior inspectable. The standalone tool is useful because its mechanical claims are finite—not because the rest of the architecture can be compressed into one green exit code.

All Gods Must Die. Valar Morghulis.