Track haddock dead-link CI failures in a rolling issue

When the haddock-links check fails on master, open (or comment on)
a single tracking issue identified by the marker label
'haddock-ci-failure', @-mentioning the breaker — sourced from the
master commit's associated PR via
listPullRequestsAssociatedWithCommit, which handles squash merges.

The issue body documents the fix recipe (add the package's doc base
URL to IOG_DOC_BASES, or add the package to KNOWN_UNDOCUMENTED).
Each failure appends a comment with the run URL so the audit trail
of consecutive breakages is visible in one place.

Add an id to the haddock-links step so the new tag-breaker step can
gate on its specific outcome (failure() && steps.<id>.outcome ==
'failure'), avoiding spurious issue creation on unrelated failures
(cabal build, nix shell, network glitch in haddock-project, etc.).

Author: Jimbo4350

.github/workflows/github-page.yml

@@ -40,6 +40,7 @@ jobs:
           cabal haddock-project --output=./website --internal --foreign-libraries
 
       - name: Fix cross-package Haddock links
+        id: fix-haddock-links
         run: |
           ./scripts/fix-haddock-links.sh ./website
 
@@ -69,3 +70,104 @@ jobs:
           publish_dir: website
           cname: cardano-api.cardano.intersectmbo.org
           force_orphan: true
+
+      # On post-merge dead-link failure, append the latest breakage to a
+      # rolling tracking issue (one issue total, comment per failure).
+      # Identified by the marker label `haddock-ci-failure`. The breaker
+      # gets @-mentioned in the comment and added as an assignee.
+      - name: Open / update dead-link tracking issue
+        if: failure() && steps.fix-haddock-links.outcome == 'failure' && github.ref == 'refs/heads/master'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const labelName = 'haddock-ci-failure';
+            const titleText = 'Haddock dead-link CI failures on master';
+
+            // Ensure the marker label exists (idempotent — 422 means
+            // already there).
+            try {
+              await github.rest.issues.createLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                name: labelName,
+                color: 'd93f0b',
+                description: 'Post-merge haddock-links CI failures (rolling tracking issue)',
+              });
+            } catch (e) {
+              if (e.status !== 422) throw e;
+            }
+
+            // Identify the breaker via the master commit's associated PR
+            // (works for squash merges, which is what cardano-api uses).
+            const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.sha,
+            });
+            const pr = prs[0];
+            const author = pr ? pr.user.login : context.actor;
+            const prRef = pr ? `#${pr.number}` : `commit ${context.sha.slice(0, 7)}`;
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+
+            const commentBody = [
+              `### New failure`,
+              ``,
+              `On master after ${prRef} (committed by @${author}).`,
+              ``,
+              `**Run:** ${runUrl}`,
+              ``,
+              `Open the run log and look for \`=== Actionable — fix these ===\` to see which package(s) the probe couldn't resolve.`,
+            ].join('\n');
+
+            // Look for an existing open issue with the marker label.
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: labelName,
+              per_page: 1,
+            });
+
+            if (issues.length > 0) {
+              const existing = issues[0];
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body: commentBody,
+              });
+              await github.rest.issues.addAssignees({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                assignees: [author],
+              });
+              console.log(`Appended to existing issue #${existing.number}: ${existing.html_url}`);
+            } else {
+              const issueBody = [
+                `Tracking issue for post-merge \`Update github pages\` workflow failures on the haddock-links check. The Deploy step skips on failure, so the published docs site stays at its last good revision until this issue is resolved.`,
+                ``,
+                `## How to fix`,
+                ``,
+                `For each package listed under \`=== Actionable — fix these ===\` in the failing run:`,
+                ``,
+                `1. Check the package's source repo for a published Haddocks site (gh-pages, CloudFront, etc.).`,
+                `2. If found: append the base URL to \`IOG_DOC_BASES\` in \`scripts/fix-haddock-links.sh\`.`,
+                `3. If genuinely unpublished: add the package name to \`KNOWN_UNDOCUMENTED\`.`,
+                ``,
+                `Then re-run the workflow from the Actions tab. Close this issue once the workflow goes green again.`,
+                ``,
+                `---`,
+                ``,
+                commentBody,
+              ].join('\n');
+              const created = await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: titleText,
+                body: issueBody,
+                labels: [labelName],
+                assignees: [author],
+              });
+              console.log(`Opened tracking issue #${created.data.number}: ${created.data.html_url}`);
+            }