feat(docs): add markdown-link-check to docs CI (#259) (#300)

* feat(docs): add markdown-link-check to docs CI (#259)

Adds a broken-link checker that validates internal cross-references and
external URLs across all Markdown sources at PR time, preventing silent
link rot in documentation that also serves as agent context.

* fix(ci): use correct actions/setup-node SHA (v6.4.0)

* fix(docs): correct broken anchor in WORKFLOWS.md

The link #domain--requiresrepo was missing the underscore; the heading
renders as #domain--requires_repo.

* fix(docs): address PR review — harden link-check and wire into drift-prevention

Remove dedicated link-check CI job from docs.yml and wire it into the
existing drift-prevention task so it runs as part of every build. Harden
the script with pipefail, temp-file approach, min-file-count assertion,
and xargs -r. Fix dead aws-cdk link in ADR-002, narrow npmjs ignore to
package paths only, drop 3xx from aliveStatusCodes, and document the
^link$ ignore pattern.

* fix(docs): regenerate Starlight mirror for ADR-002 link update

* fix(docs): correct link-check CI description to reflect drift-prevention

The check runs on every PR via the build's drift-prevention step, not
only on PRs that touch documentation.

* chore(docs): address non-blocking review suggestions

- Remove dead replacementPatterns block ({{BASEURL}} was never defined)
- Use find -print0 + xargs -0 for space-safe path handling
- Add scope comment to link-check task documenting what is/isn't scanned
- Broaden drift-prevention description to cover documentation links

* fix(docs): use npm command instead of mise in link-check script

Extract link-check logic into docs/scripts/link-check.sh and have both
package.json and mise.toml delegate to it, removing the circular mise
dependency from the npm script.

* fix(docs): scope link-check to internal links only

External http(s) URLs are now ignored so network/bot-block flakiness
cannot fail an unrelated PR, since the gate runs on every build via
drift-prevention. Removes aliveStatusCodes and the now-dead external
retry/header options, and updates the Developer Guide to match.

* fix(docs): align Workflows.md mirror anchor with sync output

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>
Co-authored-by: ayushtr-aws <ayushtr@amazon.com>
Co-authored-by: Sphia Sadek <isadeks@gmail.com>

Author: 5 people

docs/.markdown-link-check.json

@@ -0,0 +1,7 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^https?://", "_comment": "External URLs are not checked: network/bot-block flakiness must not gate every PR (drift-prevention runs on all PRs). Only internal/relative links are validated." },
+    { "pattern": "^/sample-autonomous-cloud-coding-agents/" },
+    { "pattern": "^link$", "_comment": "Masks intentional placeholder in ADR-004 example prose" }
+  ]
+}

docs/decisions/ADR-002-least-privilege-bootstrap-policies.md

@@ -68,5 +68,5 @@ The implementation is decomposed into 8 sub-issues, each independently reviewabl
 - RFC #120 — parent issue with full design and sub-issue breakdown
 - `docs/design/DEPLOYMENT_ROLES.md` — current documentation (will become generated)
 - PR #46 — original policy derivation and validation methodology
-- [CDK default bootstrap template](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml)
+- [CDK bootstrapping your environment](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping-env.html)
 - [IAM managed policy size limit](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html)

docs/design/WORKFLOWS.md

@@ -478,7 +478,7 @@ Adapted from the issue's phases (the issue framed Phase 1 as a `task_type` *alia
 | 1 | Step runner + `default/agent-v1` + migrate `new_task` to a workflow file; introduce `workflow_ref` and **remove the `task_type` enum** end-to-end (API/CLI/agent); the single workflow validator + `contracts/workflow-validation/` golden corpus | `agent/src/workflow/`, `agent/workflows/coding/new-task-v1.yaml`, `cdk/src/handlers/`, `cli/src/`, `contracts/workflow-validation/` |
 | 2b | Migrate `pr_iteration`, `pr_review` onto workflows behind a `read_only ⇒ "pr_review"` principal bridge (read-only stays enforced by the existing literal rules throughout) | `agent/workflows/coding/*`, `agent/tests/` |
 | 2a | **Cedar property-keyed read-only migration** — literal `"pr_review"` hard-deny → `context.read_only == true` rules (`read_only_forbid_write/edit`), threaded via `context.read_only`; removes the 2b bridge; adds `read-only-*` `contracts/cedar-parity/` fixtures verified on *both* engines. (Originally planned as an isolated PR ahead of 2b; reordered after 2b shipped first behind the bridge — see [ADR-014](../decisions/ADR-014-workflow-driven-tasks.md) addendum.) | `agent/policies/`, `cdk/src/handlers/shared/builtin-policies.ts`, `contracts/cedar-parity/`, `agent/src/policy.py`, `agent/src/workflow/loader.py` |
-| 3 | Repo-optional `web_research` workflow (the repo-optional refactor — see [the requires_repo note](#domain--requiresrepo)) | `cdk/src/handlers/`, `agent/workflows/knowledge/` |
+| 3 | Repo-optional `web_research` workflow (the repo-optional refactor — see [the requires_repo note](#domain--requires_repo)) | `cdk/src/handlers/`, `agent/workflows/knowledge/` |
 | 4 | Registry-native workflows (#246); Blueprint workflow allow-list + `default_workflow`; inline/repo-local for dev | depends on #246 |
 
 ## Out of scope

docs/guides/DEVELOPER_GUIDE.md

@@ -373,3 +373,5 @@ Source docs live in `docs/guides/` and `docs/design/`. The Starlight site under
 | Change how docs are synced | `docs/scripts/sync-starlight.mjs` |
 
 After editing source docs, run `mise //docs:sync` or `mise //docs:build` to regenerate the site.
+
+To validate that all cross-references are intact, run `mise //docs:link-check`. This checks all Markdown sources (`docs/guides/`, `docs/design/`, `docs/decisions/`, and root-level `.md` files) for broken internal (relative) links. The same check runs automatically in CI on every pull request, as part of the build's drift-prevention step. External `http(s)` URLs are deliberately not checked, so that network or bot-block flakiness cannot fail an unrelated PR.

docs/mise.toml

@@ -24,3 +24,9 @@ run = "./node_modules/.bin/astro dev"
 description = "astro check"
 depends = [":sync"]
 run = "./node_modules/.bin/astro sync && ./node_modules/.bin/astro check"
+
+[tasks.link-check]
+# Scope: docs/guides/, docs/design/, docs/decisions/, and root *.md files.
+# Not scanned: docs/README.md, agent/, cli/, contracts/, docs/abca-plugin/.
+description = "Check for broken links in Markdown sources"
+run = "bash scripts/link-check.sh"

docs/package.json

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+filelist=$(mktemp)
+trap 'rm -f "$filelist"' EXIT
+
+{ find guides design decisions -name '*.md' -print0; find .. -maxdepth 1 -name '*.md' -print0; } > "$filelist"
+
+count=$(tr '\0' '\n' < "$filelist" | grep -c .)
+if [ "$count" -lt 10 ]; then
+  echo "ERROR: expected ≥10 Markdown files but found $count — scan may be misconfigured" >&2
+  exit 1
+fi
+
+xargs -0 -r ./node_modules/.bin/markdown-link-check --config .markdown-link-check.json < "$filelist"

docs/scripts/link-check.sh

@@ -482,7 +482,7 @@ Adapted from the issue's phases (the issue framed Phase 1 as a `task_type` *alia
 | 1 | Step runner + `default/agent-v1` + migrate `new_task` to a workflow file; introduce `workflow_ref` and **remove the `task_type` enum** end-to-end (API/CLI/agent); the single workflow validator + `contracts/workflow-validation/` golden corpus | `agent/src/workflow/`, `agent/workflows/coding/new-task-v1.yaml`, `cdk/src/handlers/`, `cli/src/`, `contracts/workflow-validation/` |
 | 2b | Migrate `pr_iteration`, `pr_review` onto workflows behind a `read_only ⇒ "pr_review"` principal bridge (read-only stays enforced by the existing literal rules throughout) | `agent/workflows/coding/*`, `agent/tests/` |
 | 2a | **Cedar property-keyed read-only migration** — literal `"pr_review"` hard-deny → `context.read_only == true` rules (`read_only_forbid_write/edit`), threaded via `context.read_only`; removes the 2b bridge; adds `read-only-*` `contracts/cedar-parity/` fixtures verified on *both* engines. (Originally planned as an isolated PR ahead of 2b; reordered after 2b shipped first behind the bridge — see [ADR-014](/sample-autonomous-cloud-coding-agents/architecture/adr-014-workflow-driven-tasks) addendum.) | `agent/policies/`, `cdk/src/handlers/shared/builtin-policies.ts`, `contracts/cedar-parity/`, `agent/src/policy.py`, `agent/src/workflow/loader.py` |
-| 3 | Repo-optional `web_research` workflow (the repo-optional refactor — see [the requires_repo note](#domain--requiresrepo)) | `cdk/src/handlers/`, `agent/workflows/knowledge/` |
+| 3 | Repo-optional `web_research` workflow (the repo-optional refactor — see [the requires_repo note](#domain--requires_repo)) | `cdk/src/handlers/`, `agent/workflows/knowledge/` |
 | 4 | Registry-native workflows (#246); Blueprint workflow allow-list + `default_workflow`; inline/repo-local for dev | depends on #246 |
 
 ## Out of scope

docs/src/content/docs/architecture/Workflows.md

@@ -72,5 +72,5 @@ The implementation is decomposed into 8 sub-issues, each independently reviewabl
 - RFC #120 — parent issue with full design and sub-issue breakdown
 - `docs/design/DEPLOYMENT_ROLES.md` — current documentation (will become generated)
 - PR #46 — original policy derivation and validation methodology
-- [CDK default bootstrap template](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml)
+- [CDK bootstrapping your environment](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping-env.html)
 - [IAM managed policy size limit](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html)