Ship: episode renumber + audio scheme cutover (v2-renumbered-20260518)

Author: GitHub Workshop Bot

.github/workflows/validate-authoritative-sources.yml

@@ -8,7 +8,6 @@ on:
       - "classroom/**/*.md"
       - "learning-room/**/*.md"
       - "admin/**/*.md"
-      - "scripts/add-authoritative-sources.js"
       - "scripts/validate-authoritative-sources.js"
       - "package.json"
       - ".github/workflows/validate-authoritative-sources.yml"
@@ -21,14 +20,15 @@ on:
       - "classroom/**/*.md"
       - "learning-room/**/*.md"
       - "admin/**/*.md"
-      - "scripts/add-authoritative-sources.js"
       - "scripts/validate-authoritative-sources.js"
       - "package.json"
       - ".github/workflows/validate-authoritative-sources.yml"
 
 jobs:
   validate-authoritative-sources:
     runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
     steps:
       - name: Checkout
@@ -37,7 +37,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
 
       - name: Validate authoritative source sections
         run: npm run validate:authoritative-sources

.gitignore

@@ -177,3 +177,6 @@ epub/git-going-with-github.docx
 epub/git-going-with-github.brf
 epub/daisy/
 learning-room-e2e-*.json
+
+# VS Code Local History extension
+.history/

REORG-PLAN.md

@@ -0,0 +1,173 @@
+# Stage 3 Cutover - Ship Checklist
+
+Generated by the Stage 3 pre-flight on the current `main` branch. Everything
+below has been **dry-run verified**. The actual cutover is one explicit go
+away.
+
+## Pre-cutover state (verified)
+
+- **Stage 2 gate:** 5/5 PASS (`scripts/run-stage2-gate.ps1`).
+- **Map:** `docs/EPISODE_MAP.json` validates against schema 1.0.0; 79 episodes
+  (58 ep + 16 cc + 5 cc-bonus); UUIDs stable; track_number drives ordering.
+- **Audio inventory:** 79 mp3 files present in
+  `podcasts/audio/kokoro-am_liam-af_jessica/`; 58 need rename, 21 already in
+  new scheme.
+- **Working tree dirty:** 522 uncommitted files from prior Stage 1-2 work.
+  Recommend committing or stashing these before Stage 3.
+
+## Built tools (this session)
+
+| Step | Tool | Status |
+| --- | --- | --- |
+| 3.1 | `podcasts/tools/dry_run_rename.py` | Dry-run PASS |
+| 3.2 | `podcasts/tools/rename_audio.py` (--apply, --finalize-map, --chapters-dir) | Preview PASS, preflight clean |
+| 3.5 | `scripts/rewrite-cross-links.ps1` (-Apply) | Dry-run PASS, 8 files / 509 reps |
+
+## Dry-run summary
+
+```
+Stage 3.1 - rename plan
+  58 mp3 renames (e.g. ch-00-welcome.mp3 -> ch-00-welcome.mp3)
+  21 no-op (current_filename == filename)
+  CSV: tmp-proposed-rename.csv
+
+Stage 3.5 - cross-link rewrite (with .history, snapshots, transcripts excluded)
+  8 files, 509 replacements
+  Largest: admin\PODCASTS.md (174), quality_triage_report.csv/.md (224 total),
+           listening-order.json (58), validate-report.json (44)
+  Report: tmp-crosslink-rewrite-report.txt
+```
+
+## Fire sequence (locally reversible up through step 5)
+
+Run these commands in order. Each step is a separate commit so any single
+step can be reverted in isolation.
+
+### 0. Clean slate
+
+```powershell
+cd c:\code\git-going-with-github
+git checkout -b cutover-20260518
+git add -A
+git commit -m "Pre-cutover state: Stage 1-2 work product + Stage 3 tooling"
+```
+
+### 1. Rename audio + parallel chapter JSON (Stage 3.2)
+
+```powershell
+python podcasts\tools\rename_audio.py --apply --finalize-map
+git add -A
+git commit -m "Stage 3.2: rename audio to topic-prefixed filenames + finalize map"
+```
+
+Effect: 58 mp3 files renamed, 58 chapter JSON files renamed, map's
+`current_filename`/`current_slug` updated to match `filename`.
+
+### 2. Retag ID3 (Stage 3.3)
+
+```powershell
+python podcasts\tools\tag_id3.py
+python podcasts\tools\verify_id3.py
+git add -A
+git commit -m "Stage 3.3: retag ID3 frames on renamed audio"
+```
+
+Effect: TIT2, TRCK, TXXX:TOPIC updated; CHAP/CTOC untouched. Idempotent.
+
+### 3. Cross-link rewrite (Stage 3.5)
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\rewrite-cross-links.ps1 -Repo c:\code\git-going-with-github -Apply
+git add -A
+git commit -m "Stage 3.5: rewrite cross-links to new filename scheme"
+```
+
+Effect: 509 replacements across 8 files (listening-order.json, PODCASTS.md,
+quality_triage_report.*, validate-report.json, etc.).
+
+### 4. Re-run Stage 2 gate
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run-stage2-gate.ps1
+```
+
+Must return 5/5 PASS. If not, halt and investigate.
+
+### 5. Mirror to deploy repo (Stage 3.6)
+
+```powershell
+robocopy podcasts\audio\kokoro-am_liam-af_jessica c:\code\ggg\site\media *.mp3 /MIR
+```
+
+Confirm file counts match: `(Get-ChildItem c:\code\ggg\site\media\*.mp3).Count`.
+
+### 6. Regenerate feed + site (Stages 3.7 - 3.8)
+
+```powershell
+cd c:\code\ggg
+node generator\generate-site.js
+node generator\validate-feed.js
+```
+
+Spot-check `c:\code\ggg\site\feed.xml`. Confirm `<enclosure url>` points to
+the new filenames. (Cover art piece intentionally omitted per project
+constraint.)
+
+### --- IRREVERSIBLE LINE ---
+
+Steps below affect remote systems. Confirm step 6 looks correct before
+proceeding.
+
+### 7. Deploy (Stage 3.9)
+
+```powershell
+c:\code\ggg\deploy-ggg.ps1 -Backup
+c:\code\ggg\deploy-ggg.ps1 -DryRun     # review the rsync delta
+c:\code\ggg\deploy-ggg.ps1             # live
+```
+
+### 8. Smoke-test remote
+
+- `curl -I https://lp.csedesigns.com/ggg/feed.xml` -> 200
+- Three sample enclosure URLs -> 200
+- Three episode pages -> 200
+
+### 9. Tag (Stage 3.10)
+
+```powershell
+cd c:\code\git-going-with-github
+git checkout main
+git merge --no-ff cutover-20260518
+git tag v2-renumbered-20260518
+git push origin main --tags
+
+cd c:\code\ggg
+git tag v2-renumbered-20260518
+git push origin main --tags
+```
+
+## Rollback (steps 1-5)
+
+Any of steps 1-5 can be reverted with:
+```powershell
+git reset --hard HEAD~1
+```
+
+For audio rename specifically, `tmp-rename-audit.log` records every
+old -> new pair so a reverse rename script can be reconstructed.
+
+## What's intentionally excluded
+
+- **Cover art** (`<itunes:image>` in feed) - skipped per project constraint.
+- **`.history/` files** - VS Code Local History snapshots, not rewritten.
+- **`podcasts/_snapshot-pre-*/`** - intentional historical reference.
+- **`podcasts/transcripts/`** - workflow artifacts that key off old slug names
+  in their own filename scheme; do not need rewrite for cutover.
+
+## Notes
+
+- All 522 currently-uncommitted files come from prior Stage 1-2 sessions.
+  They have been validated by the Stage 2.8 gate. Committing them in step 0
+  is the cleanest restore point.
+- The cutover branch should be `cutover-20260518` per the REORG-PLAN.md
+  specification.