Incognito-Wiki/docs/superpowers/plans/2026-08-03-publish-legacy-pdfs.md

Publish Legacy PDFs Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Publish all 332 permission-cleared legacy PDFs through a searchable Starlight archive without changing their bytes.

Architecture: Public files retain their DokuWiki-derived hierarchy under public/media/legacy-dokuwiki/. A generated Markdown catalog and explicit supplemental-content registry make the collection discoverable while keeping the original 29-page migration manifest unchanged.

Tech Stack: Astro 7, Starlight 0.41, Node.js 22, Markdown, Node test runner, Poppler pdfinfo.

Global Constraints

• Publish exactly the 332 records in docs/pdf-inventory.tsv.
• Preserve PDF bytes, relative namespace paths, sizes, and SHA-256 checksums.
• Record the maintainer's 2026-08-03 permission confirmation.
• Preserve unrelated working-tree changes.
• Do not deploy or push.

---

Task 1: Define the supplemental publication contract

Files:

• Create: docs/supplemental-content.json
• Modify: scripts/audit-content.mjs
• Modify: tests/content-audit.test.mjs

Interfaces:

• Consumes: original destinations from docs/migration-manifest.json

• Produces: an allowlist of { destination, source, category } records loaded by auditContent

• Step 1: Write failing audit tests proving a declared supplemental page is accepted, an undeclared page is rejected, and a registry destination missing from disk is rejected.

• Step 2: Run node --test tests/content-audit.test.mjs and confirm the declared supplemental-page test fails.

• Step 3: Add docs/supplemental-content.json with the PDF archive destination and implement strict registry loading and validation in scripts/audit-content.mjs.

• Step 4: Run node --test tests/content-audit.test.mjs and confirm all content-audit tests pass.

Task 2: Publish and verify the recovered files

Files:

• Move: to-be-studied/legacy-pdfs/study/** to public/media/legacy-dokuwiki/study/**
• Modify: docs/pdf-inventory.tsv
• Modify: docs/pdf-publication-review.tsv
• Modify: docs/pdf-publication-review.md
• Modify: docs/pdf-archive.md
• Modify: to-be-studied/README.md
• Create: scripts/verify-pdf-archive.mjs
• Create: tests/pdf-archive.test.mjs

Interfaces:

• Consumes: current inventory rows and staged PDFs

• Produces: byte-identical public files plus a verifier that returns counts and throws on missing files, size mismatches, checksum mismatches, duplicate public paths, or malformed PDF signatures

• Step 1: Write failing verifier tests using temporary valid-signature fixtures for success, missing-file, byte-count, and checksum cases.

• Step 2: Run node --test tests/pdf-archive.test.mjs and confirm failure because the verifier does not exist.

• Step 3: Implement the verifier and update inventory/review documentation to public URLs and permission-confirmed status.

• Step 4: Move each inventoried file with an explicit source/destination mapping, leaving no recovered PDF in the non-public staging directory.

• Step 5: Run the verifier and pdfinfo over all public PDFs; expect exactly 332 successes and matching hashes.

Task 3: Add the searchable archive page

Files:

• Create: src/content/docs/previous-exams-and-documents.md
• Modify: src/config/sidebar.mjs
• Modify: src/content/docs/bachelor/index.md
• Modify: src/content/docs/master-ai/index.md
• Modify: src/content/docs/master-dsdm/index.md
• Modify: tests/content-audit.test.mjs

Interfaces:

• Consumes: the normalized docs/pdf-inventory.tsv

• Produces: /previous-exams-and-documents/ with exactly one working link per inventory record

• Step 1: Write failing tests for archive frontmatter, sidebar registration, programme links, link count, and one-to-one inventory URL coverage.

• Step 2: Run the focused tests and confirm they fail before the page exists.

• Step 3: Generate the archive Markdown grouped by programme/course namespace with human-readable labels and original filenames.

• Step 4: Add sidebar and programme links and replace wording that still calls the recovered archive non-public.

• Step 5: Run npm run verify and confirm the full site, rendered output, and internal links pass with all 332 PDFs present in dist/.