The Revival, Revived, in four tiers

The repo we inherited was written almost entirely by an autonomous agent loop — “ralph,” set up and steered by the project’s creator, Norman Nunley, iterating against a roadmap for months. What it produced is genuinely impressive: a working language with a bytecode VM, a PEG grammar engine, an object system, and a parser that generates itself. What it also produced is the sediment of its own process: a 107-file .agent/ memory system, 41 files of “superpowers” process documentation, ralph driver scripts, run logs, a bespoke .git-issue/ tracker, and prompt files — roughly 30,000 lines of machinery about building the thing, interleaved with the thing.

And the repo did not build. Not subtly: cargo build failed at manifest resolution, before compiling a line, because one workspace member had a path dependency on execution_tape — a “verified bytecode VM” crate that existed on exactly one machine, and this wasn’t it. Cargo resolves every member’s manifest before building any of them, so the missing path failed everything, including cargo build -p fmpl-cli. The agent never noticed because the agent never had to do a fresh clone.

The first day was recon before surgery: a static read plus live runs of the REPL, TUI, and web app, written up as findings before any code changed. That ordering was deliberate. With an inherited codebase — especially an agent-inherited one — the temptation is to start fixing what you see; the discipline is to first record what is actually true, because you will not get a second chance to observe the artifact undisturbed.

The central judgment call of the whole rehabilitation: what to do with the agent’s machinery. Deleting it would have been clean and irreversible — and wrong twice over. The harness is part of the project’s story (the tour says plainly that the implementation is agent-written), and it may be useful again if an autonomous loop resumes. Keeping it in place was also wrong: a public repo where the first thing a visitor meets is the scaffolding, not the building.

The answer was a third category. Everything the agent needed and a human doesn’t was moved — intact, in one commit — to an archive/agent-harness branch. Nothing was deleted; the main branch simply stopped carrying it. The same commit unified the agent’s CLAUDE.md into a single human-and-agent AGENTS.md, later split again into lean workflow rules plus a DEV.md inventory. The test of the triage: in the days since, nobody has needed the process machinery back from the archive — though agent-era feature work off the same lineage (the ITER-0005 persistence arc — durable TupleSpace, content-addressed recovery, bytecode persistence — on branches this fork predated) was since grafted onto main and now underpins active design. The scaffolding was disposable; the code beneath it was not. Keeping the archive costs nothing, and it makes the history honest.

The work was planned as tiers with a deliberate order — each one meaningless without the one below it — and built as a stack of branches, each on the previous, so the whole thing could be reviewed bottom-up and landed as one fast-forward:

The ordering encodes a belief about inherited code: credibility is restored outside-in. A stranger’s first five minutes are clone, build, run an example from the README, hit an edge. Ergonomic polish on a repo that doesn’t build is decoration; deep test work before the harness is sidelined gets tangled in machinery that’s about to move.

The repo had never had CI — the agent ran its own checks, on its own machine, in its own environment. The very first CI run failed twice, and both failures were the same lesson wearing different clothes: properties nobody asserts are properties nobody has.

The first failure was the determinism check: regenerate the parser twice, byte-compare. The outputs differed every run — grammar rules travel through a HashMap, so each generator process emitted the parser’s functions in a different random order. Rust doesn’t care about definition order, so ~1,390 tests had been green for months over a nondeterministic build. The fix was one sort; the point is that the assertion had existed the whole time as an ignored test nobody ran.

The second was humbler: CI installs the latest stable toolchain, and its clippy was newer than the local one, with new lints. A locally-clean build is only evidence about the local toolchain. That became a standing rule in AGENTS.md — keep local Rust current, because a clean local clippy is not proof of a green CI.

A third repair completed the set: the checked-arithmetic work from Tier 4 had moved a panic rather than removing it — the generated parser’s digit-fold actions were emitted with .unwrap() on the newly-fallible ops. Threading Result through generated grammar actions (and rejecting the tempting catch_unwind shortcut, which would have poisoned VM mutexes) is the change that started the parser-generator epoch history at 6 — the same counter the next arc drove to 9.

The suite we inherited had ~185 ignored tests with no stated reasons — indistinguishable from neglect, and unusable as a map. The Tier 4 pass read every one, grouped them by root cause, wrote a machine-readable reason into each #[ignore], and distilled the result into docs/known-gaps.md: metacircular parser (~120), pattern matching (~50), pending design decisions, odds and ends.

This was the quiet keystone of the whole revitalization. An agent-written test suite encodes months of intent — tests written ahead of features, aspirational behavior pinned before it exists — but intent you can’t read is indistinguishable from cruft. Turning the ignore pile into a ledger did two things: it made the repo honest to visitors (the count reads as roadmap, not rot), and it made progress measurable. The payoff came fast: the next arc picked the ~120 bucket off the top of the ledger, burned it to zero in two days, and could prove it — because the ledger defined what zero meant.

Publishing had its own fork points. The upstream repo wasn’t pushable (403 — no access), which settled the topology: a fork carries the work, upstream remains the lineage. The rehabilitated history needed to be reviewable without being mergeable — the fork’s main already contained everything — which produced the advisory-PR convention: freeze a pre-rehab branch at the inherited tip, open a PR from main against it, mark it review-only, close it when read. The frozen base is the “before” snapshot; merging would destroy it. That convention outlived the rehab — every phase since gets an advisory PR based on the previous phase’s frozen tip.

The last mile was the engineering tour: a single page that says what the thing is, what provably works, and what honestly doesn’t — every claim in it verified against a fresh REPL, like the TUTORIAL sweep before it. GitHub Pages hosting came with one classic paper cut: Jekyll choked on the design docs, so .nojekyll ships in docs/. (Pages later moved to Actions-based deploys in the wasm arc; the file remains as a fossil of this one.)

Revitalizing an agent-written codebase turned out to differ from ordinary legacy work in one repeated way: the artifact is strong where humans are weak, and weak where humans are strong. The agent never got tired, so the language core is deep and the test suite vast. The agent never changed machines, so the build was broken for everyone else on earth. Its review and roadmap lived inside its own process layer — PAR adversarial audits, an iteration log, a behavior-scenario corpus — so to an outside reader who never opened that layer, nothing on the surface distinguished roadmap from rot. Every tier addressed some version of that asymmetry — and the fixes were mostly social artifacts, not code: a README, a ledger, a review convention, an archive, CI as an outside observer.

What the later arcs inherited from this one: a build a stranger can run, a ledger that made “burn down the bucket” a measurable goal, an advisory-PR convention still in use at #5 and #6, the epoch discipline for generated-parser changes, and the habit — docs verified against a live REPL — that grew into the doctest harness in the very next phase.