Clean-room derivation

GridWork independently implements terminal multiplexing and agent orchestration — domains where established projects carry copyleft (AGPL/GPL) licenses. This project is Apache-2.0, and its independence is procedural, not just textual. This document is the public record of that procedure, in force since before any engine code existed.

Method

1. No derived code. Code copied, ported, or mechanically translated from any copyleft or otherwise incompatibly-licensed project is never accepted — from maintainers, agents, or external contributors (see CONTRIBUTING.md). Concept-level inspiration from public, documented behavior is fine; derivation is not.

2. Engine authors don't read copyleft source. Whoever implements code under the paths listed in .github/cleanroom-paths.txt does not read the source of copyleft terminal multiplexers — before or during that work. Behavior is derived from public specifications and observed wire behavior only.

   What gets listed is a category, not a directory. Any path whose code supervises an engine process or a PTY session — spawn, pump loop, restart semantics, session registry, detach/reattach routing — or emits or parses terminal-protocol bytes is gated, at whatever module granularity keeps the tax off lens code.

   The granularity clause is the point, not a softening. A crate is rarely all one thing: the parity harness is a pure data model plus a set of runners that spawn and kill engine children, and gating the whole crate to reach the runners would put a review tax on check functions that never see a process. So the runners are listed and the rest is not. The gate follows the risk; the directory tree is just where the risk happens to sit this week.

   Two mechanical consequences, because a category rule enforced by memory is a rule that decays into whatever the last person assumed:

   • Every crate is classified. A crates/ directory matches a gated prefix or carries a line in .github/cleanroom-not-engine.txt saying why it is outside. Neither is not an option, and the gate refuses to pass on an unclassified crate. A crate is not ungated because nobody looked.
   • A direct gwk-pty dependency gates the crate. It links the PTY engine, so it is gated by that fact and not by its name. Without this, coverage came down to whether a crate happened to be called gwk-pty-host rather than gwk-host — and nothing anywhere would have said which one you got.

   Lens code is deliberately outside, and that is a ruling rather than an accident of where the files landed. The console renders projections the kernel already computed and consumes engine output as wire data; it does not supervise anything and does not speak the terminal protocol. Its multiplexer half — panes, layout, detach and reattach routing — is gated, and lives under its own listed prefix for exactly that reason. Drawing the line inside the crate is what keeps the review where the copyleft-adjacent risk actually is.

   Library-mediated terminal I/O is exempt. Reading key and mouse events through crossterm, or painting through ratatui, is using a permissively-licensed dependency's public API — the same act as calling any other crate. It emits no protocol bytes of our authorship and derives nothing from anyone's source. Writing those sequences ourselves is the gated thing; asking a library to is not.

What every gated change carries

Every gated change carries stable citation IDs and an independent second reader record.

3. Every non-obvious terminal behavior carries a derivation citation — the public spec it implements or a captured observation, cited by stable ID from docs/derivation/SPECS.md or docs/derivation/CAPTURES.md. The citation is a Derivation: marker on the line above the derived construct:

   // Derivation: ECMA-48 §8.3.20 — CUF advances the active position by Pn, default 1

   Check the section number against the specification, not against another marker. This example previously read §8.3.14 — cursor save/restore semantics and was wrong twice: §8.3.14 is CPR, a device report that moves nothing, and ECMA-48 defines no cursor save/restore at all — DECSC/DECRC are DEC private and belong under XTERM-CTLSEQS. The gate resolved it happily, and the first real marker written in this repo copied the wrong number straight out of this block. A wrong example propagates further than a wrong line of code.

   cleanroom-gate enforces this mechanically: every gated source file carries at least one marker, and every cited ID resolves in one of the two registries. Never cite a source by path — rule 4's references check bans it, and the gate rejects it.

   A behavior with no citable permitted source is an escalation, not a guess.

   A file that derives nothing says so, rather than inventing a citation. The gate keys on file extension, not content, so a gated crate's skeleton — or a re-export, or a config module — owes a marker it has nothing truthful to fill in. The declaration form is rule 3's answer:

   // Derivation: none — skeleton only: no process spawned, no byte parsed

   The reason is mandatory; a bare Derivation: none is not a marker and the gate keeps rejecting the file. A none may not sit beside a real citation — a file derives nothing or it names its sources, never both, and the failure direction is why: a reviewer who sees the none stops looking and never checks the citation next to it. This is not a way out of an awkward behavior. A behavior with no citable permitted source is still an escalation, not a none.

   What the gate proves is that the claim was made and that the source is registered. It does not prove the claim is TRUE — a marker can name a spec the code did not come from, or the right spec with the wrong section, and only rule 4's reader catches that. The gate makes a false citation attributable; the review is what makes it unlikely. That is not hypothetical: it is how the two errors above were found.

4. Independent second review. Every change touching the clean-room paths gets an additional fresh-context review before it reaches main, checking exactly this: citations present and resolving, no source-derived framing, no other project named as a comparand and no capture cited by path, leak gate green. The reviewer is a fresh-context session with no exposure to the implementing session — not a second human: this repository has one maintainer, and claiming a control it cannot deliver would be worse than stating the narrower one plainly. The review is recorded in docs/derivation/reviews/, bound by digest to the exact content it read — the gated files and the registry rows their markers cite, so neither half of a citation can be rewritten under a standing record — and the cleanroom-gate check enforces that the record exists and matches.

What this proves

Process, not similarity. Nobody on the reviewing side compares this codebase against copyleft sources — doing so would itself breach rule 2. What the record shows is that every behavior traces to a permitted source, and that the trail was written at commit time rather than reconstructed after a question was raised.

What it does not show is reviewer independence. No status check can establish that, and rule 4 says what the reviewer actually is instead of implying more.

Follow the public trail through permitted specifications, captured observations, and second-reader records.