docs: Pages site cleanup step 1 - curated publish set + cross-link fixes (#51)

* docs: step 1 of the docs/site cleanup - whitelist Pages site config, fix cross-links to excluded docs, drop game-behavior-reference index bullet Publish only the curated set (index/building/internals/porting-notes/ dev-process/agentic-development); everything else under docs/ stays in the repo but out of the Pages build and sitemap. Cross-links from the published pages to excluded docs now point at GitHub blob URLs so they still resolve. No content rewrite yet -- steps 2-5 (README update, per- page descriptions, light copy passes, repo hygiene) remain. Claude-Session: https://claude.ai/code/session_016TaKy6AAsVUTfjkhrX6CjG * docs(dev-process): add §6 -- keep PR/git-history noise low Squash-merge single-purpose/docs PRs, batch same-session docs updates into one branch instead of one-PR-per-finding, keep unrelated housekeeping off active branches, declare stacked-PR dependencies, and triage the open-PR list every session -- close stale PRs (superseded by newer main content) rather than force-merging or endlessly rebasing them. Prompted by this session's PR #26: real conflicts against main because D191/D193/D149 were all fixed/closed since it was opened; closed rather than rebased.
2026-10-23 15:52:42 +02:00 · 2026-09-11 17:31:36 -04:00
1 parent b577008543
commit 4d45e78176
@@ -3,8 +3,8 @@
 title: GoldenEye 007 PC Port
 description: >-
  A native PC port of the original Nintendo 64 GoldenEye 007, built from its
-  decompiled source, and a case study in AI-agent collaboration on a large
-  low-level codebase.
+  decompiled source with a software RSP — plus the engineering record:
+  internals, porting notes, and the two-agent development workflow.
 theme: jekyll-theme-cayman
 show_downloads: false

@@ -26,26 +26,46 @@ plugins:
  - jekyll-sitemap

 # jekyll-relative-links (on by default for Pages) rewrites the .md links in
-# these docs to .html so cross-links work on the published site.
+# these docs to .html so cross-links work on the published site. Links that
+# must reach docs kept out of the site build point at the GitHub blob URL
+# instead, so they resolve from the published pages too.

-# Rolling local working files - not useful as published pages.
+# ---------------------------------------------------------------------------
+# The site publishes a small curated set (see docs/dev/notes/DE-SLOP-DOCS-PLAN.md):
+#   index.md, building.md, internals.md, porting-notes.md, dev-process.md,
+#   dev/agentic-development.md
+# Everything else under docs/ is working material - the finding log, level
+# status, backlogs, plans, inherited decomp guides. It stays in the repo (and
+# on GitHub) but is excluded from the site build so it never shows up as a
+# published page or in sitemap.xml.
 exclude:
+  - BACKLOG.md
  - HANDOFF.md
-
-# Keep the raw engineering record (finding log, per-level status, triage
-# notes, backlogs) out of sitemap.xml so search engines aren't steered at it.
-# The pages still build and stay reachable from cross-links; the two dev/
-# docs that are linked from the site index are kept in.
-defaults:
-  - scope:
-      path: "dev"
-    values:
-      sitemap: false
-  - scope:
-      path: "dev/agentic-development.md"
-    values:
-      sitemap: true
-  - scope:
-      path: "dev/game-behavior-reference.md"
-    values:
-      sitemap: true
+  - SetupGuide.md
+  - StructureGuide.md
+  - StyleGuide.md
+  - dev/AUDIO-PLAN.md
+  - dev/AUDIT-M6-player-offsets.md
+  - dev/D172-PARTICLE-COLOR-RESEARCH.md
+  - dev/D176a-SKY-NOTES.md
+  - dev/GE-ENV-PROBES.md
+  - dev/GRAPHICS-BACKLOG.md
+  - dev/HANDOFF-ARCHIVE.md
+  - dev/LEVEL-OBJECTIVES.md
+  - dev/LEVEL-PLAYTEST.md
+  - dev/LEVEL-STATUS.md
+  - dev/LINUX-PORT.md
+  - dev/M-35-PLAYTEST-CHECKLIST.md
+  - dev/M-35-QOL-REVIEW.md
+  - dev/M-36-TRIAGE.md
+  - dev/MODERN-PORT-FEATURES-BACKLOG.md
+  - dev/OPTIONS-MENU-PLAN.md
+  - dev/QOL-INVENTORY.md
+  - dev/TEXTURE-GLITCH-ANALYSIS.md
+  - dev/UNLOCKED-FPS-PLAN.md
+  - dev/VIEWMODEL-RESEARCH.md
+  - dev/WIDESCREEN-FOV-PLAN.md
+  - dev/findings-index.csv
+  - dev/findings.md
+  - dev/game-behavior-reference.md
+  - dev/release-dropin-rom-plan.md
@@ -43,9 +43,9 @@ binutils), `make`, `git`, and `python3`. They build a small host-compiled
 `tools/extractor` and slice blobs straight out of the ROM — **no IDO / IRIX
 toolchain is involved in extraction or in the PC build.** (The IDO toolchain is
 only needed to build the N64 ROM itself, and its proprietary SGI binaries are
-not distributed here — see [`SetupGuide.md`](SetupGuide.md) "Recompile IDO".)
+not distributed here — see [`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md) "Recompile IDO".)
 On Windows this is easiest under WSL or a Linux VM. Full details and
-alternatives (Docker) are in [`SetupGuide.md`](SetupGuide.md).
+alternatives (Docker) are in [`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md).

 ---

@@ -70,7 +70,7 @@ and run:
 (US extraction is a prerequisite for the others.)

 This populates `assets/` with the generated `.bin` blobs the build needs. See
-[`SetupGuide.md`](SetupGuide.md) for the in-depth build/asset pipeline.
+[`SetupGuide.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/SetupGuide.md) for the in-depth build/asset pipeline.

 ---

@@ -158,4 +158,4 @@ runtime. `ge007.ini` is written under `data/` on first launch.
 | `GE_PCDUMP="first-last:step"` | dump rendered frames as PPM (debugging) |

 More diagnostic switches are cataloged in
-[`dev/GE-ENV-PROBES.md`](dev/GE-ENV-PROBES.md).
+[`dev/GE-ENV-PROBES.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GE-ENV-PROBES.md).
@@ -41,7 +41,8 @@ more room.
 Lewis's agents recorded generalisable IDO quirks in a learnings file; later
 agents read it and did better. Our equivalent is
 [`porting-notes.md`](porting-notes.md) — the recurring N64→PC bug classes,
-each entry a terse index into the full [`dev/findings.md`](dev/findings.md)
+each entry a terse index into the full
+[`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md)
 log. Every investigation brief links it, and every investigation ends by
 appending any new generalisable quirk.

@@ -91,6 +92,44 @@ Then hand the agent the *findings*, not just the problem.
  inverted here — the hard part is identifying the implicit hardware/ABI
  contract the already-readable C depends on.

+## 6. Keep PR/git-history noise low
+
+A session produces a lot of small, independently-verifiable units of work —
+one Dxx row, one docs pass, one mechanical fix. Left unmanaged that turns
+into a pile of small open PRs that's harder to review than the work
+justifies. Rules:
+
+- **Squash-merge single-purpose and docs-only PRs.** The repo has squash
+  merge enabled; use it (`gh pr merge --squash --delete-branch`) for anything
+  whose in-branch commit history (iteration, probe-add, probe-strip) isn't
+  itself useful to keep — which is most PRs. Reserve a plain merge commit for
+  a PR whose individual commits are each a distinct, reviewable unit someone
+  might want to `git revert` independently (e.g. this session's PR #50: a
+  fix commit + a separate analysis-only commit).
+- **Batch same-session, same-flavor docs updates into one PR/branch**
+  instead of opening a new PR per finding row. A runtime re-check that
+  updates one `findings.md` row (like #48) doesn't need its own PR if
+  another docs-only branch is already open in the same session — fold it in.
+  Only split into separate PRs when the pieces have genuinely different
+  review/merge timing (e.g. one needs a human playtest, the other doesn't).
+- **A branch takes only the change it's named for.** Don't let unrelated
+  housekeeping (a stray gitignore fix, a config tweak) ride along on an
+  active feature/fix branch just because it's the one checked out — cut a
+  separate branch, even for a one-line change.
+- **Stacked PRs declare the dependency in the title/body** ("step 2 of N,
+  step 1 is #N") and get rebased/merged in order promptly — don't let a
+  later step sit open so long the earlier step's content drifts under it.
+- **Triage the open-PR list at least once a session**, ordered by
+  time-to-close (docs-only and non-draft first, human-playtest-gated last).
+  A PR idle long enough that `main` has moved past the finding rows it
+  touches is **stale, not just old** — check for real textual conflict
+  (`git merge-tree`), not just calendar age. If `main` already has more
+  current information than the PR (a bug the PR still lists `OPEN` that's
+  since been fixed and verified), **close it rather than force a merge or
+  spend a cycle rebasing it** — re-derive only whatever part of its content
+  is still true as a fresh, small PR against current `main`. Merging stale
+  content back over newer information is a regression, not a save.
+
 ## Investigation-brief template

 ```
@@ -106,7 +106,7 @@ issues still outstanding.
 |---|---|
 | Calendar time | 16 days (16 Aug – 1 Sep 2026), one person part-time |
 | Commits on the port | ~223 |
-| Root-caused bugs logged | 162 (`D1`–`D169` in [`findings.md`](findings.md); some later merged or withdrawn) |
+| Root-caused bugs logged | 162 (`D1`–`D169` in [`findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md); some later merged or withdrawn) |
 | Handoff sessions | ~33 (`M-2` … `M-33`) |
 | Game-source files given `#ifdef PORT` ABI edits | 63 files, 241 blocks |
 | New port-layer / tooling files | 128 |
@@ -261,4 +261,5 @@ Honest notes, for anyone weighing whether this transfers.

 **Still outstanding** (parked below crash/level work): audio is not
 implemented; several front-end 3D transforms and some text rendering are
-wrong. See [`GRAPHICS-BACKLOG.md`](GRAPHICS-BACKLOG.md).
+wrong. See
+[`GRAPHICS-BACKLOG.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/GRAPHICS-BACKLOG.md).
@@ -30,5 +30,4 @@ and cutscenes are rough.
 - **[Development process](dev-process.md)** — how work was scoped, partitioned, and budgeted across agents; the finding-log discipline.
 - **[Internals](internals.md)** — architecture, the software RSP-emulation approach, GoldenEye-vs-Perfect-Dark engine differences, the phased plan.
 - **[Porting notes](porting-notes.md)** — the recurring Nintendo 64 → PC bug classes hit during the port, with fixes.
- **[Game-behavior reference](dev/game-behavior-reference.md)** — how the retail N64 game is meant to behave: combat/AI model, difficulty scaling, per-level objectives, timers, weapon data, and the original game's known quirks.
 - **[Building](building.md)** — full build and asset-extraction guide.
@@ -5,8 +5,9 @@
 > external references. The phased plan in section 8 is largely done through
 > Phase 2 — for current status see the
 > [README](https://github.com/jkdansereau/goldeneye-pc-port#status) and
-> [`dev/LEVEL-STATUS.md`](dev/LEVEL-STATUS.md); for the blow-by-blow finding
-> log see [`dev/findings.md`](dev/findings.md).
+> [`dev/LEVEL-STATUS.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/LEVEL-STATUS.md);
+> for the blow-by-blow finding log see
+> [`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md).

 This document captures the research done to plan a PC port of
 GoldenEye 007, based on the decompilation this repository is forked from
@@ -4,7 +4,8 @@ A field guide to the bug classes that keep recurring when running big-endian
 32-bit N64 game code, unmodified, on a little-endian 64-bit host. Terse by
 design — each entry compresses a full investigation to a symptom, a fix, and a
 grep heuristic for finding siblings. Each entry cites a `Dxx` label; the full
-evidence and fix for that instance live in [`dev/findings.md`](dev/findings.md)
+evidence and fix for that instance live in
+[`dev/findings.md`](https://github.com/jkdansereau/goldeneye-pc-port/blob/main/docs/dev/findings.md)
 under the same label. Skim the section headers; read the classes relevant to
 the task at hand.