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

docs/.markdown-link-check.json

@@ -0,0 +1,20 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^https?://localhost" },
+    { "pattern": "^https?://127\\.0\\.0\\.1" },
+    { "pattern": "^https?://example\\.com" },
+    { "pattern": "^https?://www\\.npmjs\\.com/package/", "_comment": "npmjs returns 403 to automated requests; retryOn429 does not cover this" },
+    { "pattern": "^/sample-autonomous-cloud-coding-agents/" },
+    { "pattern": "^link$", "_comment": "Masks intentional placeholder in ADR-004 example prose" }
+  ],
+  "httpHeaders": [
+    {
+      "urls": ["https://github.com"],
+      "headers": { "Accept": "text/html" }
+    }
+  ],
+  "retryOn429": true,
+  "retryCount": 3,
+  "fallbackRetryDelay": "10s",
+  "aliveStatusCodes": [200, 206]
+}

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

@@ -476,7 +476,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 and external links. The same check runs automatically in CI on every pull request, as part of the build's drift-prevention step.

docs/mise.toml

@@ -24,3 +24,21 @@ 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 = """
+#!/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/src/content/docs/architecture/Workflows.md

@@ -480,7 +480,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](/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/decisions/Adr-002-least-privilege-bootstrap-policies.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)

mise.toml

@@ -89,12 +89,13 @@ description = "Generate commands stubs from .abca/commands for multiple AI assis
 run = "node scripts/sync-abca-commands.mjs"
 
 [tasks."drift-prevention"]
-description = "Run checks to prevent drift in contracts between packages"
+description = "Run checks to prevent drift in contracts between packages and documentation links"
 run = [
   { task = "sync:abca-commands" },
   { task = "check:constants-sync" },
   { task = "check:types-sync" },
   { task = "check:coverage-thresholds-sync" },
+  { task = "//docs:link-check" },
 ]
 
 ##################