Skip to content

SHIP-CHECKLIST.md

Latest commit

 

History

History
192 lines (140 loc) · 6.22 KB

SHIP-CHECKLIST.md

File metadata and controls

192 lines (140 loc) · 6.22 KB

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

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)

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)

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 -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 -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)

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)

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)

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)

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:

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.

Authoritative Sources

Use these official references when you need the current source of truth for this checklist.

Section-Level Source Map

Use this map to verify facts for each major section in this file.