docs: design internal migration comments

docs/superpowers/specs/2026-08-03-internal-migration-comments-design.md

@@ -0,0 +1,31 @@
+# Internal Migration Comments Design
+
+## Goal
+
+Remove editorial migration-state messages from the public Starlight site while preserving the information for repository maintainers as source comments.
+
+## Public notices that remain visible
+
+- Historical-information cautions, including page-level outdated-content warnings and the 2022 study-abroad warning.
+- Reader-actionable warnings, including the University network-use warnings.
+- Historical course-list notes, because they explain the status and time context of content readers can see.
+
+## Notices moved into source comments
+
+- Every `Awaiting content` callout on empty honours-programme pages and empty Handy Locations sections.
+- Both `Missing source asset` callouts for the Year 1 and Year 2 schedule image.
+- The statements on the Bachelor, Master AI, and Master DSDM overview pages that course summaries and old exams were absent from the export.
+
+Use HTML comments in Markdown/MDX so maintainers retain the source-export context without rendering it in the generated site. Keep the affected pages, headings, and empty course/section structure intact.
+
+## Verification
+
+Update the content tests before changing published content. The tests must verify that:
+
+- all targeted information exists as HTML comments;
+- none of the targeted text is present as visible Markdown or Starlight callouts;
+- historical and reader-actionable notices remain present;
+- empty pages and section headings remain in the content tree;
+- the complete content audit, Astro build, rendered-output check, and internal-link check pass.
+
+Finally, inspect representative affected pages in the running site to confirm the internal comments are absent from rendered output and the retained public warnings remain visible.