hygiene: Organize public handoffs and preserve active workspace evidence

.github/workflows/docs-consistency.yml

@@ -23,5 +23,5 @@ jobs:
         run: python tools/docs_reorg.py --check-links --check-findings --check-root
       - name: Pure-Python pipeline tests
         run: |
-          python -m pip install pytest
+          python -m pip install pytest numpy Pillow lupa
           python -m pytest tools/decomp_pipeline/tests tools/script_recovery -q -k "not vc71 and not retail"

.gitignore

@@ -4,6 +4,9 @@
 imgui.ini
 *.user
 *.suo
+.junie/
+/.claude/worktrees/
+/.agents/CLEANUP_COORDINATION.md
 
 # Proprietary/local binary inputs and analysis databases
 /debug_build/
@@ -14,6 +17,10 @@ imgui.ini
 /work/
 /dist/
 /tmp/
+/build/
+/.scratch_tmp/
+/scratchpad/
+/runtime_dumps/
 /snapshots/
 /FSE/
 /FableTLC_RE_docs.zip
@@ -87,4 +94,9 @@ imgui.ini
 /CON
 /imgui.ini
 /out_dat.txt
+/tmp_*
+/work_*.txt
+/*_native.txt
+/*.log
+/0x*
 /[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*

CONTRIBUTING.md

@@ -57,3 +57,9 @@ comparison. Root-level scratch (`*.obj`, `*.bin`) is ignored; keep working files
 
 Open an issue with the function address, the verifier output, and the compiler flags used.
 For readability complaints about landed code, name the file; a retype pass exists exactly for that.
+
+## Working alongside other sessions
+
+See [project layout and workspace care](docs/PROJECT_LAYOUT.md) for source and
+local-output locations, exact path ownership, and isolated publication. Preserve
+active builds and evidence even when ignored by Git.

README.md

@@ -4,7 +4,7 @@ An evidence-gated reconstruction of the native 32-bit Windows
 `Fable.exe`, targeting readable, buildable C/C++ source and a durable native
 modding platform.
 
-> **Actively developed — October 10, 2026.** Native C/C++ reconstruction is
+> **Actively developed — October 24, 2026.** Native C/C++ reconstruction is
 > continuing. Recent local tests render a retail title sprite through recovered
 > drawing routines and validate connected texture-loading and lifetime paths.
 > The existing interactive frontend is an authored integration checkpoint,
@@ -14,7 +14,8 @@ modding platform.
 [Run the checkpoint](#run-the-checkpoint) ·
 [See current progress](#current-progress) ·
 [Read the roadmap](#roadmap) ·
-[Browse the documentation](#documentation)
+[Browse the documentation](#documentation) ·
+[Project layout and workspace care](docs/PROJECT_LAYOUT.md)
 
 <a id="contents"></a>
 ## Contents

docs/HANDOFF.md

@@ -1,49 +1,35 @@
-# Public handoff — updated 2026-10-10
-
-## Current public checkpoint
-
-Native recreation is active. Read [NATIVE_STATUS.md](NATIVE_STATUS.md) for the
-October 10 local verification results, current boundaries and publication scope.
-This update publishes status only; the newer local source/test checkpoint is
-not merged into `main`. The generated dashboard remains the September snapshot.
-The published frontend is authored integration, not a playable native engine.
-
-The resume instructions below are historical September notes. Their branch,
-head, clean-tree and `main` equality claims are not current instructions.
-Do not blindly merge the development branch: unrelated Lua work must stay out
-of a native-only publishing checkpoint.
-
-## Historical September 7 handoff
-
-## State
-- Branch: `feat/script-recovery-marathon` (head `2e038aa`, clean tree, `main` == this head); `main` was fast-forwarded (519 commits) and pushed to `BuffJesus/FableDecomp` on 2026-09-07 — fast-forward it again after each checkpoint. Note: `git add` on this tree takes 1–6 minutes and HANGS if another process is writing under `rebuild/` (or a reserved-name file like `CON` exists); never run it concurrently with the header generator or retype.
-- 22 old agent branches are now `archive/*` tags. Root scratch + `CON` removed. `LICENSE`, `CONTRIBUTING.md`, CI `docs-consistency` added.
-- Coverage (2026-08-28 dashboard): 8,082 byte-identical (16.3%), 18,579 functional-or-matching (37.5%) of 49,568; catalog is now 18,631 landed. Regenerate `rebuild/COVERAGE.md` before quoting numbers.
-
-## Open these five first
-1. `docs/ROADMAP.md` — what is done / in flight / next (the only task list)
-2. `docs/ARCHITECTURE.md` — the three source layers (lift intake / parity `rebuild/src/compiled` / modern)
-3. `docs/BUILDING.md` — Ghidra, VC7.1, GhidraMCP, FSE tooling commands
-4. `CONTRIBUTING.md` — landing rules, header contract, purity policy
-5. `rebuild/COVERAGE.md` — the numbers
-
-## Active lanes and their resume commands
-- Typed headers: `python tools/decomp_pipeline/gen_class_headers.py --all-trusted` (add `--compile-check`), then `python tools/decomp_pipeline/retype_landed.py --class CGameScriptInterface` (dry run; `--apply` only rewrites files that stay byte-exact). Log: `rebuild/backlog/retype_log.tsv`; headers: `rebuild/include/engine/` (`INDEX.tsv`, `RECONCILE.tsv`, `_quarantine/`).
-- Parity crawl: resume from `work/crawl_batch155` — `next_smallest.py` -> `trim_overcapture.py` -> `trim_tailjmp.py` -> author -> `verify_and_land.py`; iterate a DIFFER with `work/crawl_batch154/probe.py`. Ledger `tools/decomp_pipeline/crawl/gen_tried.txt`.
-- De-bake: `python tools/decomp_pipeline/crawl/bake_families.py` for the live family table; `debake_family.py <template> <genuine.cpp> <prefix> --apply`.
-- Script recovery: `python -m unittest discover -s tools/script_recovery -p 'test_*.py'`; `python tools/script_recovery/verify_foundation.py`; readiness needs `--vtable-slots`, `--interface-catalog`, `--fse-address-map`. Ingest Aeon's 2026-09-06 LUAGameflow batch into `work/aeon_lua_ports/`.
-- ForgeFSE: canonical fork is `D:\Code\ForgeFSE-retail-shadow`, branch `feat/upstream-fse-2026-09-02` (`3f417ee`), untested in-game. `D:\Code\ForgeFSE` is stale.
-- Docs hygiene: `python tools/docs_reorg.py --check-links --check-findings --check-root` and `python tools/update_readme_progress.py --check` (both run in CI).
-- Build/visual QA: `rebuild/build_bootstrap.ps1 -RetailFrontendBank <frontend.big>`; recipe in `docs/pipeline/VISUAL_PARITY_STATUS.md`. Retail Fable.exe must be CLOSED (single-instance mutex fails the WinMain fixture).
-
-## Where notes go
-- This file stays one page. The long-running journal is `docs/journal/HANDOFF_ARCHIVE.md` (12k lines, append-only history).
-- New session notes: `docs/journal/YYYY-MM/<TOPIC>_<date>.md` (e.g. `docs/journal/2026-09/`). Cited technical truth: `docs/journal/FINDINGS_LOG.md`.
-- Solved gotchas get a one-liner in `CLAUDE.md`; roadmap status changes go in `docs/ROADMAP.md`.
-
-## Gotchas not yet in CLAUDE.md
-- A file named `CON` at the repo root hangs EVERY git command on Windows (reserved device name). Delete it with `del "\\?\D:\Documents\FableTLC\CON"` — normal `del`/Explorer cannot.
-- A killed `git add` leaves a stale `.git/index.lock`; remove it before retrying (check no git process is running first).
-- Sibling repos hold the moved modding docs: FableForge `D:\Code\FableForge\docs\from_fabletlc\` and ForgeFSE-retail-shadow `docs\from_fabletlc\`. `docs/modding/README.md` is the index; do not recreate those docs here.
-- `native_conversion_readiness.json` silently loses all interface resolution if regenerated without `--vtable-slots` and `--interface-catalog`.
-- Two ForgeFSE forks existed; only `ForgeFSE-retail-shadow` is canonical. Any binding port must land there.
+# Public handoff - October 24, 2026
+
+## Published checkpoint
+
+Native reconstruction and separate C++23/x64 modernization work are active.
+The public source remains an earlier reviewed checkpoint. Newer local source,
+fixtures, and evidence are not included in this documentation update.
+
+The published interactive frontend is an authored integration checkpoint.
+It does not establish a playable reconstructed native or modern engine.
+See [NATIVE_STATUS](NATIVE_STATUS.md) for dated results and their limits.
+The generated coverage dashboard retains its published snapshot; new bounded
+test counts have not been added to whole-executable coverage.
+
+## Start here
+
+1. [ROADMAP](ROADMAP.md): current priorities and publication gates.
+2. [PROJECT_LAYOUT](PROJECT_LAYOUT.md): source locations, local scratch, and parallel-work rules.
+3. [ARCHITECTURE](ARCHITECTURE.md): native parity and modernization boundaries.
+4. [BUILDING](BUILDING.md): toolchain and reproduction commands.
+5. [CONTRIBUTING](../CONTRIBUTING.md): landing and evidence requirements.
+
+The [documentation index](INDEX.md) covers reference topics and dated journals.
+
+## Resume safely
+
+Use the current owning session's local handoff when continuing an active lane.
+A public status page is not an instruction to restart another session's jobs.
+Coordinate path ownership before changing shared files; publish from an
+isolated checkout. Do not merge accumulated development work without reviewing
+its dependencies and separating unfinished or unrelated experiments.
+
+Historical September resume commands and clean-tree/branch claims are preserved
+in the [October 10 public handoff archive](journal/2026-10/2026-10-10-public-handoff.md).
+They are historical evidence, not current execution instructions.

docs/INDEX.md

@@ -6,8 +6,10 @@ Generated by `tools/docs_reorg.py --index`; do not edit by hand.
 
 - [ARCHITECTURE](ARCHITECTURE.md) — Source architecture and modernization
 - [BUILDING](BUILDING.md) — Toolchain & exact commands
-- [HANDOFF](HANDOFF.md) — Resume here (one page) — updated 2026-09-07
-- [ROADMAP](ROADMAP.md) — FableTLC roadmap (single source of truth for "what's done / in flight / next")
+- [HANDOFF](HANDOFF.md) — Public handoff - October 24, 2026
+- [NATIVE_STATUS](NATIVE_STATUS.md) — Native development update - October 24, 2026
+- [PROJECT_LAYOUT](PROJECT_LAYOUT.md) — Project layout and workspace care
+- [ROADMAP](ROADMAP.md) — FableTLC roadmap
 
 ## Engine reverse engineering
 
@@ -169,5 +171,7 @@ Generated by `tools/docs_reorg.py --index`; do not edit by hand.
 - [BACKLOG_pre-roadmap](journal/2026-09/BACKLOG_pre-roadmap.md) — FableTLC RE / decomp / modding BACKLOG (prioritized)
 - [PLAN_pre-roadmap](journal/2026-09/PLAN_pre-roadmap.md) — Fable: The Lost Chapters — Decompilation Plan
 - [SESSION_HANDOFF_2026-09-01_SCRIPT_RECOVERY](journal/2026-09/SESSION_HANDOFF_2026-09-01_SCRIPT_RECOVERY.md) — ForgeFSE retail-script recovery handoff — 2026-09-01
+- [2026-10-10-public-handoff](journal/2026-10/2026-10-10-public-handoff.md) — Public handoff — updated 2026-10-10
+- [2026-10-10-public-roadmap](journal/2026-10/2026-10-10-public-roadmap.md) — FableTLC roadmap (single source of truth for "what's done / in flight / next")
 - [FINDINGS_LOG](journal/FINDINGS_LOG.md) — FINDINGS — cited technical truth
 - [HANDOFF_ARCHIVE](journal/HANDOFF_ARCHIVE.md) — HANDOFF — resume here

docs/NATIVE_STATUS.md

@@ -1,4 +1,32 @@
-# Native development update — October 10, 2026
+# Native development update - October 24, 2026
+
+Native reconstruction continues locally. The concrete text-bank composition
+checkpoint passed 108 bounded processes covering text, group, and narrator
+metadata, with 18 native fault controls. These are composition-test results,
+not an increase in whole-executable coverage. Decoded payloads and nonempty
+resource ownership remain under investigation; no full `gate_all` run or
+playable engine is claimed.
+
+Separate C++23/x64 subsystem libraries and offline replay tests also exist
+locally. This does not certify a playable modern engine or a complete headless
+gameplay session. Scheduling and ownership joins continue through their own
+qualification and promotion gates.
+
+This publication updates organization and status only. Newer native and modern
+source, fixtures, generated reports, local receipts, and retail-derived inputs
+remain outside this change pending dependency-complete review. The published
+coverage dashboard keeps its existing snapshot.
+
+See [the handoff](HANDOFF.md), [current priorities](ROADMAP.md), and
+[workspace organization](PROJECT_LAYOUT.md) for navigation and safe continuation.
+
+## Historical October 10 checkpoint
+
+The following results and unresolved boundaries describe October 10. Later
+bounded composition work above does not establish that all of these earlier
+boundaries have been closed.
+
+### Native development update — October 10, 2026
 
 The project is active. Work has continued locally on faithful native PC
 C/C++ reconstruction, rather than Lua recovery. The gap in public commits

docs/PROJECT_LAYOUT.md

@@ -0,0 +1,66 @@
+# Project layout and workspace care
+
+Start with [HANDOFF](HANDOFF.md) for the public checkpoint, [ROADMAP](ROADMAP.md)
+for current priorities, and [INDEX](INDEX.md) for the full documentation catalog.
+
+## Source and evidence locations
+
+| Location | Purpose |
+|---|---|
+| `rebuild/src/compiled/` | Curated VC7.1 reconstruction, organized by native address |
+| `rebuild/include/` | Shared engine layouts and subsystem declarations |
+| `rebuild/tests/` | Behavior fixtures and integration tests |
+| `rebuild/modern/` | Separate C++23/x64 subsystem work |
+| `tools/decomp_pipeline/` | Native reconstruction and verification tools |
+| `tools/modern/` | Modernization preparation and validation tools |
+| `tools/script_recovery/` | Lua recovery tools and tests |
+| `docs/engine/`, `docs/formats/`, `docs/pipeline/`, `docs/scripts/`, `docs/modern/` | Reference documentation by topic |
+| `docs/journal/YYYY-MM/` | Dated results, failed attempts, and historical checkpoints |
+| `refs/`, `ghidra_out/`, `lift/` | Curated analysis inputs, exports, and intake records |
+| `work/`, `build/`, `rebuild/build/` | Local scratch, builds, and evidence; retained locally |
+| `scratchpad/`, `runtime_dumps/`, `.scratch_tmp/` | Local captures and temporary experiments |
+
+New experiments belong under `work/<topic>/<date>/`. Keep native source at its
+existing address-based path until dependency and parity checks justify a move.
+Keep related receipts beside the experiment; a failed attempt can still explain
+a current restriction. Ignoring a file does not make it safe to delete.
+
+## Parallel work
+
+Before cleanup, identify active sessions and registered worktrees with
+`git worktree list` and coordinate exact path ownership with their owners.
+Record local ownership in `.agents/CLEANUP_COORDINATION.md` when using that
+workspace convention. Keep local session identifiers out of public documents.
+
+Use an isolated checkout for public updates. Do not switch, stash, reset, stage,
+or commit the shared checkout while another session is writing there. Build
+outputs, source snapshots, failed attempts, and prior evidence may be live test
+dependencies even when old. Relocation, deletion, or compression needs an exact
+reviewed scope and a coordinated timing window.
+
+The local maintenance catalog and its saved project shortcuts provide navigation
+without relocating projects. Saved inventory dates describe past observations;
+they do not establish that a folder is currently unused.
+
+## Public updates
+
+Publish an explicit file list from a clean checkout and inspect the staged diff.
+Do not merge a development branch solely to make the public activity look
+current. A status update can describe qualified local work while source remains
+under review; state that distinction in [NATIVE_STATUS](NATIVE_STATUS.md).
+
+Never publish retail binaries, proprietary symbols, game assets, decoded
+payloads, local captures, or raw byte-oracle evidence. Keep user-supplied inputs
+and their generated products local. See [CONTRIBUTING](../CONTRIBUTING.md).
+
+Before publication, run:
+
+```powershell
+python tools/docs_reorg.py --index
+python tools/docs_reorg.py --check-links --check-findings --check-root
+python tools/update_readme_progress.py --check
+git diff --check
+```
+
+Regenerate coverage only from a settled, reviewed reconstruction checkpoint.
+Composition-test counts and CTest totals are not whole-executable coverage.