The reverse-engineering method

This whole course rests on two maps — alembic-complete-map.md and hermes-complete-map.md — and a fusion matrix derived from them. None of it is trustworthy unless the method that built them is. This lesson teaches that method: honest depth tiers, Proof-Gate everything, builder ≠ validator, and "the code wins." It is the discipline behind the fusion, and it generalizes to any codebase you ever have to understand from the outside.

Principle 1 — the code wins, always

The map's own header states the rule: it maps "the real filesystem as built, not the design intent in HANDOFF.md — where the two diverge, the code wins and the divergence is noted." This is the foundation. Design docs describe intent; intent drifts. A reverse-engineering map that trusts the doc over the source inherits every lie the doc has accumulated:

// docs/alembic-complete-map.md — the discipline, stated up front
// "This document maps the real filesystem as built, not the design intent in
//  HANDOFF.md — where the two diverge, the code wins and the divergence is noted."
// e.g. HANDOFF says "11 packages / 284 tests"; the tree has 19 packages + 1 app,
//      415 tests — the map reflects the decomposition, and names the drift.

The map literally records where the handoff was stale (11 vs 19 packages, 284 vs 415 tests) and where a "known bug" was actually fixed (contrarian-last, lesson 16). That honesty is the deliverable — a map that quietly papered over the divergence would be worse than no map.

Principle 2 — honest depth tiers

You cannot read every line of every file at the same depth — and pretending you did is the most common reverse-engineering lie. The method instead declares its depth explicitly:

In the Alembic map this shows up concretely: the narrow waist, the funnel, council, and swarm get deep treatment with line citations; the long tail (infra, docs, tui, web) gets a structured catalog (responsibility / API / deps / tests / gaps); and genuine unknowns are marked [uncertain] — e.g. "[uncertain] whether real source drivers live in another package or are not yet implemented," "[uncertain] whether any infra tests run under vitest." The frontier is named, not hidden.

Principle 3 — Proof-Gate everything

The fusion matrix's method note is explicit: "Nothing here is decided from memory; every 'Alembic has/lacks X' cites map evidence." Claims are backed by verifiable artifacts — a file:line you can open, a hit-count you can reproduce with grep, a test that exists. This is the same Proof Gate discipline the engine itself uses (lesson 17), turned inward on the documentation:

• Every non-obvious claim cites a path and, where useful, a line number — clickable, checkable.
• Capability presence/absence is grounded in hit-counts over the map ("memory=1 incidental hit; no memory package" ⇒ it's a genuine gap).
• Verified state is stated with the command that produced it ("npx vitest list → 415 cases").

Principle 4 — builder ≠ validator

The same separation the engine enforces (lesson 18's Verifier, lesson 17's Validator Gate) governs the documentation work itself. The course you are reading was written by one agent and reviewed by a different one — the brief that produced these lessons states "Builder ≠ validator" as a hard rule. A map checked only by its author inherits its author's blind spots; an independent reviewer is the human-and-agentic version of the read-only Verifier.

Common confusions