docs(agents): the plan to consolidate six repositories into two #29

Merged

fabi merged 3 commits from plan/consolidation into main 2026-09-15 19:46:20 +00:00

Conversation 1 Commits 3 Files Changed 1 +461

fabi commented 2026-09-13 17:02:50 +00:00

Owner

Copy Link

The ordered plan for the two-repo end state, with a gate after each phase.

docs/agents/CONSOLIDATION.md — 8 phases, and a ledger of what was run rather than reasoned.

What the verification changed

Three findings a plan built on the obvious reading would have destroyed:

1. 🔴 The F1 instrument is uncommitted. xenia-canary has two dirty files — file_input_driver.h (--pad_file_repeat) and xenia_main.cc — plus 4 unpushed commits on sylpheed-re and a branch, audit-handle-lifecycle-probes, contained in no remote. That patch is the instrument behind the repeat rate shipped in #27. Phase 0 exists for it, before anything else moves.
2. xenia-rs has 4 unpushed branches (4B/ui-perf, 4C/jit, 4D/parallel, 4E/native-threads). Dropping the emulator is a decision; dropping work that was never pushed is a different act, done by accident. Phase 1 pushes them so that retiring them is honest.
3. The DuckDB tool is not on master, which last moved 2026-06-15. It's on iterate-4A/apu-xma-stage1, +22 commits, 2026-09-10.

What was verified safe

claim	method	result
Reborn absorbed	21 remote + 8 local tips vs main	all ancestors
Sylpheed-Godot absorbed	2 tips + root graft	all ancestors
agent-backups/ (687 MB) redundant	git bundle list-heads, 23 refs	all present
3 unpushed pi/* redundant	git patch-id --stable	all 4 patches on main
nothing outside git	issues/PRs/releases/wikis ×6	zero outside Sylpheed

On dropping docs/re/captures/

The measurement contradicted the premise. 193 of 257 files are cited by a page or opened by a tool, and two are fixtures cargo test opens (title-screen-oracle.png, stage02-live-unit-definitions-deep.txt). 64 are orphans.

So Phase 4 does the thing that was actually missing: docs/port/*.md has had a citation check since day one and docs/re/*.md never has. It already has 10 dangling citations, including whole directories. The check gets built, the citations get fixed, and only then are orphans dropped — otherwise the deletion silently ratifies every omission.

And deleting reclaims nothing: the 118 MB is history, and the build depends on this repo by tag (formats-pin-2026-09-01, pinned in Cargo.lock). That's Phase 5's explicit fork, not a default.

Three things left for you in the doc

Retention (all six repos are public, and 118 MB of game screenshots sit in one), the history-rewrite fork, and whether ai-agent-*.md / scratch/ / _voice_span.rs are worth keeping.

⚠️ Most paths in this doc don't resolve here yet — deliberately. They name the files being moved in, and each unresolved one is work outstanding. Said so at the top so a future citation check reads correctly.

The ordered plan for the two-repo end state, with a gate after each phase. **`docs/agents/CONSOLIDATION.md`** — 8 phases, and a ledger of what was *run* rather than reasoned. ### What the verification changed Three findings a plan built on the obvious reading would have destroyed: 1. 🔴 **The F1 instrument is uncommitted.** `xenia-canary` has two dirty files — `file_input_driver.h` (`--pad_file_repeat`) and `xenia_main.cc` — plus 4 unpushed commits on `sylpheed-re` and a branch, `audit-handle-lifecycle-probes`, **contained in no remote**. That patch is the instrument behind the repeat rate shipped in #27. Phase 0 exists for it, before anything else moves. 2. **xenia-rs has 4 unpushed branches** (`4B/ui-perf`, `4C/jit`, `4D/parallel`, `4E/native-threads`). Dropping the emulator is a decision; dropping work that was never pushed is a different act, done by accident. Phase 1 pushes them *so that* retiring them is honest. 3. **The DuckDB tool is not on `master`**, which last moved 2026-06-15. It's on `iterate-4A/apu-xma-stage1`, +22 commits, 2026-09-10. ### What was verified safe | claim | method | result | |---|---|---| | Reborn absorbed | 21 remote + 8 local tips vs `main` | all ancestors | | Sylpheed-Godot absorbed | 2 tips + root graft | all ancestors | | `agent-backups/` (687 MB) redundant | `git bundle list-heads`, 23 refs | all present | | 3 unpushed `pi/*` redundant | `git patch-id --stable` | all 4 patches on `main` | | nothing outside git | issues/PRs/releases/wikis ×6 | zero outside Sylpheed | ### On dropping `docs/re/captures/` The measurement contradicted the premise. **193 of 257 files** are cited by a page or opened by a tool, and **two are fixtures `cargo test` opens** (`title-screen-oracle.png`, `stage02-live-unit-definitions-deep.txt`). 64 are orphans. So Phase 4 does the thing that was actually missing: `docs/port/*.md` has had a citation check since day one and **`docs/re/*.md` never has**. It already has **10 dangling citations**, including whole directories. The check gets built, the citations get fixed, and only *then* are orphans dropped — otherwise the deletion silently ratifies every omission. And deleting reclaims nothing: the 118 MB is history, and the build depends on this repo **by tag** (`formats-pin-2026-09-01`, pinned in `Cargo.lock`). That's Phase 5's explicit fork, not a default. ### Three things left for you in the doc Retention (all six repos are public, and 118 MB of game screenshots sit in one), the history-rewrite fork, and whether `ai-agent-*.md` / `scratch/` / `_voice_span.rs` are worth keeping. ⚠️ Most paths in this doc don't resolve here yet — deliberately. They name the files being moved *in*, and each unresolved one is work outstanding. Said so at the top so a future citation check reads correctly.

fabi added 1 commit 2026-09-13 17:02:50 +00:00

docs(agents): the plan to consolidate six repositories into two ... e54fe16077

The end state the human set: Sylpheed holds the port, the corpus and every
tool; the Canary fork holds the emulator and oracle. Four repos retire.

Eight phases, each with a gate. What matters more than the sequence is the
ledger: every absorption claim here was RUN, not reasoned.

  Reborn's 21 remote + 8 local branch tips  -> all ancestors of Sylpheed/main
  Sylpheed-Godot's 2 tips + the root graft  -> all ancestors
  agent-backups/, 23 refs across 4 bundles  -> all present in Sylpheed
  3 unpushed pi/* branches, by patch-id     -> all 4 patches already on main
  issues / PRs / releases / wikis, 6 repos  -> zero outside Sylpheed

Three things the check found that a plan built on the obvious reading would
have destroyed:

1. The F1 instrument -- Canary's --pad_file_repeat patch, the one behind the
   repeat rate now shipped in the port -- is UNCOMMITTED, alongside 4 unpushed
   commits and a branch contained in no remote. Phase 0 exists for this.
2. xenia-rs has 4 unpushed branches of JIT/multicore/native-threads work.
   Dropping the emulator is a decision; dropping work that was never pushed is
   a different act, done by accident.
3. The DuckDB tool is not on master, which last moved 2026-06-15. It is on
   iterate-4A/apu-xma-stage1, +22 commits, 2026-09-10.

On the captures question the measurement contradicted the premise: 193 of 257
files are cited by a page or opened by a tool, and two are fixtures that
cargo test opens. 64 are orphans. Phase 4 builds docs/re/ the citation check
docs/port/ has had all along -- it already finds 10 dangling citations -- and
fixes those BEFORE deleting orphans, so the deletion cannot ratify them.

Deleting reclaims nothing anyway: the 118 MB is in history, and the build
depends on this repo by tag (formats-pin-2026-09-01, pinned in Cargo.lock).
That is Phase 5's explicit fork rather than a default.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fabi added 1 commit 2026-09-13 17:18:58 +00:00

docs(agents): phases 0-1 done, and the Phase 2 gate corrects the page ... 1ebb924851

PHASE 0 -- the single-copy work is secured. Canary 8e63a9542 commits the
--pad_file_repeat instrument that had been uncommitted while the numbers it
produced were already shipping in the port; sylpheed-re and
audit-handle-lifecycle-probes pushed; all 14 local branches reachable.

Two corrections found by running it:

  * There is no DirectXShaderCompiler gitlink drift. `git submodule status`
    shows no '+'. The ' m' is NESTED submodule dirt (DXC's own SPIRV-Headers
    and SPIRV-Tools), which is upstream's business.
  * The gate itself was wrong. It compared branches to remotes BY SHA and
    called seven safe branches unpushed -- a branch that is an ANCESTOR of a
    pushed branch is already preserved. It now tests reachability, which is
    what it meant. A check that goes red for something unactionable is the
    failure this repo keeps naming, and this page shipped one.

PHASE 1 -- the four retiring xenia-rs branches pushed (32/52/56/59 commits).
The loop is clean everywhere except pi/clippy, pi/clippy-clean and pi/reauth3,
unreachable by ancestry and redundant by patch-id: the one case where the
answer lives outside the gate.

PHASE 2 GATE -- run, and it corrected this page in two directions.

  extract      (xex2tractor, no -r)    IDENTICAL to the project .pe
  extract -r   (xex2tractor)           differs -- 1,903 bytes over 273 runs
  extract      (xenia-rs, iterate-4A)  IDENTICAL, and .xex.json too

Right: the .pe is an xex2tractor extract. Wrong: it was made WITHOUT -r. So
the dependency this gate existed to protect does not exist -- the tool Phase 3
keeps already reproduces the file. -r drops from 'must port' to optional, with
a warning that it must never become the .pe, since it writes into the image
and would invalidate every byte-offset citation in docs/re/.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fabi added 1 commit 2026-09-13 19:22:49 +00:00

docs(agents): record the progress, and correct four claims this page got wrong ... b7087517f2

Paused at six of eight phases, all committed and pushed, nothing left in a
working tree. The page now carries a STATUS section the other machine can
finish from: what is done, which PR each phase is in, what to run next, and
what is deliberately left for the human.

🔴 FOUR THINGS THIS PAGE ASSERTED WERE WRONG, and each is corrected in place
rather than quietly amended:

  * "10 dangling citations" was ONE. Eight were DIRECTORY references, which
    resolve and are absent only from `git ls-tree`; one was a path ending a
    sentence, with the full stop pulled into the match. I reported that 10 to
    the human twice.
  * `extract -r` is not how the .pe was made and nothing depends on it. The
    plain extract is, and the tool Phase 3 keeps reproduces it byte-for-byte.
  * The Phase 0 gate compared branches by SHA and called seven safe branches
    unpushed -- a branch that is an ancestor of a pushed one is preserved.
  * There is no DirectXShaderCompiler drift; the ' m' is nested submodule dirt.

The pattern is worth more than the corrections: every claim that was REASONED
turned out wrong, and every one that was RUN held. Phase 2's gate refuted its
own premise, Phase 3's proved two alarming row deltas were an improvement, and
Phase 4's check caught a deletion I had just made. The page now says to re-run
the gates rather than trust the results recorded in it.

Phase 5 (archive) and Phase 7 (drops) are open and marked NOT STARTED, with
the reason each needs the human: archiving is reversible and deleting a
repository is not, and the drops are on the human's disk.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fabi commented 2026-09-13 19:23:07 +00:00

Author

Owner

Copy Link

Paused at six of eight phases. Everything is committed and pushed; nothing is left in a working tree. This comment is the handoff.

Done

phase
0 secure single-copy work	✅	Canary 8e63a9542, sylpheed-re + audit-handle-lifecycle-probes pushed
1 honest archive	✅	xenia-rs 4B/4C/4D/4E pushed — 32/52/56/59 commits
2 harvest xex2tractor	✅	#30
3 lift the DB tool	✅	#32
4 captures + the missing check	✅	#33
6 adopt orphan assets	✅	#34, + Canary 99cc72662
— containers and agents	✅	#31

Open

Phase 5 — archive the four repos. Re-run containment at that moment, archive read-only, and 🔴 do not delete any repository — archiving is reversible, deletion is not, and that is a separate decision. Nothing outside git needs migrating: issues, PRs, releases and wikis are zero in all four, verified.

Phase 7 — the drops. All verified, none done, because they are deletions on the human's disk: agent-backups/ 687 MB (23 refs verified present here), Sylpheed/target 32 GB, stock-oracle/ 34 MB, root canary_*.log 15 MB, xenia-rs audit-runs/ 57 MB, and the three pi/* branches whose four patches are on main by patch-id.

The history-rewrite fork is still open and still recommended against: the 118 MB is in history, and crates/sylpheed-export/Cargo.toml depends on this repo by tag.

⚠️ Merge order

#32 contains #30 and #31 — its build.rs needs #30's export table. Merge those two first, or merge #32 and close them.

⏳ One result outstanding: the workspace cargo test count for #32. check, clippy, fmt, wasm are all 0; the test leg was interrupted twice by branch switches and never reported cleanly. docker/ci/run cargo test --workspace.

🔴 Four claims in this document were wrong, and are corrected in it

• "10 dangling citations" was one. Eight were directory references that resolve; one was a full stop pulled into the regex. I reported that 10 twice.
• extract -r is not how the .pe was made and nothing depends on it.
• The Phase 0 gate compared by SHA, calling seven safe branches unpushed.
• There is no DXC submodule drift — the m is nested submodule dirt.

The pattern matters more than the corrections: every claim that was reasoned turned out wrong, and every one that was run held. Phase 2's gate refuted its own premise, Phase 3's proved two alarming −1.8 M row deltas were an improvement, and Phase 4's check caught a deletion I had just made. The page now says to re-run the gates rather than trust the numbers recorded in it.

**Paused at six of eight phases.** Everything is committed and pushed; nothing is left in a working tree. This comment is the handoff. ### Done | phase | | | |---|---|---| | **0** secure single-copy work | ✅ | Canary `8e63a9542`, `sylpheed-re` + `audit-handle-lifecycle-probes` pushed | | **1** honest archive | ✅ | xenia-rs `4B/4C/4D/4E` pushed — 32/52/56/59 commits | | **2** harvest xex2tractor | ✅ | #30 | | **3** lift the DB tool | ✅ | #32 | | **4** captures + the missing check | ✅ | #33 | | **6** adopt orphan assets | ✅ | #34, + Canary `99cc72662` | | — containers and agents | ✅ | #31 | ### Open **Phase 5 — archive the four repos.** Re-run containment *at that moment*, archive read-only, and 🔴 **do not delete any repository** — archiving is reversible, deletion is not, and that is a separate decision. Nothing outside git needs migrating: issues, PRs, releases and wikis are **zero** in all four, verified. **Phase 7 — the drops.** All verified, none done, because they are deletions on the human's disk: `agent-backups/` 687 MB (23 refs verified present here), `Sylpheed/target` **32 GB**, `stock-oracle/` 34 MB, root `canary_*.log` 15 MB, xenia-rs `audit-runs/` 57 MB, and the three `pi/*` branches whose four patches are on `main` by patch-id. **The history-rewrite fork** is still open and still recommended *against*: the 118 MB is in history, and `crates/sylpheed-export/Cargo.toml` depends on this repo **by tag**. ### ⚠️ Merge order **#32 contains #30 and #31** — its `build.rs` needs #30's export table. Merge those two first, or merge #32 and close them. ⏳ One result outstanding: the workspace `cargo test` count for #32. `check`, `clippy`, `fmt`, `wasm` are all 0; the test leg was interrupted twice by branch switches and never reported cleanly. `docker/ci/run cargo test --workspace`. ### 🔴 Four claims in this document were wrong, and are corrected in it * **"10 dangling citations" was one.** Eight were *directory* references that resolve; one was a full stop pulled into the regex. I reported that 10 twice. * **`extract -r` is not how the `.pe` was made** and nothing depends on it. * **The Phase 0 gate compared by SHA**, calling seven safe branches unpushed. * **There is no DXC submodule drift** — the ` m` is nested submodule dirt. The pattern matters more than the corrections: **every claim that was reasoned turned out wrong, and every one that was run held.** Phase 2's gate refuted its own premise, Phase 3's proved two alarming −1.8 M row deltas were an improvement, and Phase 4's check caught a deletion I had just made. The page now says to re-run the gates rather than trust the numbers recorded in it.

fabi referenced this pull request 2026-09-14 18:46:03 +00:00

docs(agents): the gate that cannot see a working tree, and the Phase 5/7 checks re-run #36

fabi merged commit 9b74d0d71f into main 2026-09-15 19:46:20 +00:00

fabi referenced this issue from a commit 2026-09-15 19:46:21 +00:00

Merge pull request 'docs(agents): the plan to consolidate six repositories into two' (#29) from plan/consolidation into main

fabi referenced this issue from a commit 2026-09-19 20:29:49 +00:00

Merge pull request 'docs(agents): the plan to consolidate six repositories into two' (#29) from plan/consolidation into main

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

agent/decoder

Owned by the Decoder (disc to meaning; runs the emulator)

agent/port

Owned by the Port (disc to playable; no RE)

kind/ask

One agent asking the other for something it cannot answer in role

kind/bundle

A bundle the human defined; agents decompose it into items

kind/defect

Found by a play-test or a check

kind/item

One unit of work, small enough to finish in a single session

state/approved

Human approved the shape; an agent may start

state/blocked

Waiting on another item; use the Depends-On field, not prose

state/in-progress

An agent is working it now

state/needs-human

Done as far as an agent can tell -- a person must look. The body says what to look at

state/proposed

Agent proposed this item; awaiting the human's approval to start

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

sylph-decoder sylph-pi sylph-port fabi

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: fabi/Sylpheed#29