Task: Implement Hotfix: release notes export produces broken/relative id links

Table of Contents

This page documents a task in the Hotfix: release notes export produces broken/relative id links story. It captures the goal, current status, acceptance, and any notes or results.

Goal

`ores-build-release-notes.el` never called `org-id-update-id-locations`, unlike every other `ores-build-*.el` exporter, so `id:` links pointing outside `release_notes.org` itself (e.g. to knowledge-base docs) rendered as `[BROKEN LINK: <uuid>]` in the exported `release_notes.md` — the GitHub release body. Additionally, the exporter had no custom `id` link handler at all, so once resolution was fixed the links would have rendered as relative `.md` paths that don't exist standalone in a GitHub release body. Fix both: resolve `id:` links repo-wide before export, and render them as absolute URLs into the published site (`https://orestudio.github.io/OreStudio/…`), matching the convention already established in `ores-build-manual.el`.

Status

Field Value
State DONE
Parent story Hotfix: release notes export produces broken/relative id links
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-08-03

Acceptance

  • No `BROKEN LINK` placeholders in the exported `release_notes.md` for sprint 24.
  • `id:` links in the exported markdown resolve to real, live `https://orestudio.github.io/OreStudio/…` URLs (verified via curl).
  • The fix lives in the shared exporter (`ores-build-release-notes.el`), so every future sprint's release notes benefit automatically.

Plan

  1. Add `org-id-update-id-locations` over the whole repo (excluding `.claude/worktrees/`) before export, mirroring `ores-build-site.el`/`ores-build-manual.el`.
  2. Add a custom `id` link `:export` handler resolving via `org-id-find`, rewriting `.org` -> `.html`, and prefixing with `ores/release-notes-site-base-url`. Had to check `(org-export-derived-backend-p backend 'md)` rather than `'gfm` – ox-gfm derives from ox-md and link transcoding reports the backend as `md`, verified via a standalone debug script.
  3. Re-ran `compass release-notes export –sprint 24` and confirmed zero `BROKEN LINK` occurrences and that the resolved URLs return HTTP 200 against the live GitHub Pages site.

Notes

Test Scenarios

Manual QA scenarios (scaffolded via compass add test_scenario, run through the QA Validation Runner panel) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Scenario State Notes
     

PRs

PR Title
   

Review

Comment summary File Decision Notes
       

Result

Added a repo-wide `org-id-update-id-locations` scan and a custom `id` link `:export` handler to `ores-build-release-notes.el`, resolving `id:` links to absolute `https://orestudio.github.io/OreStudio/…` URLs. Re-exported `release_notes.md` for sprint 24: zero `BROKEN LINK` occurrences remain, and the resolved URLs were verified live against the published GitHub Pages site (HTTP 200). The fix is in the shared exporter, so it applies to every future sprint's release notes, not just this one.

Emacs 29.3 (Org mode 9.6.15)