From e4aa417a773a4ef1d0cbc67cf84f1ffd164cdf39 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 9 Jun 2026 16:43:55 -0400 Subject: [PATCH 1/7] 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. --- .github/workflows/docs.yml | 29 +++ docs/.markdown-link-check.json | 24 ++ docs/guides/DEVELOPER_GUIDE.md | 2 + docs/mise.toml | 7 + docs/package.json | 4 +- .../docs/developer-guide/Project-structure.md | 4 +- yarn.lock | 239 +++++++++++++++++- 7 files changed, 302 insertions(+), 7 deletions(-) create mode 100644 docs/.markdown-link-check.json diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0687ff55..f1d3183c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -10,13 +10,42 @@ on: - docs/scripts/** - .github/workflows/docs.yml - CONTRIBUTING.md + pull_request: + paths: + - docs/** + - docs/guides/** + - docs/design/** + - docs/decisions/** + - .github/workflows/docs.yml + - CONTRIBUTING.md + - AGENTS.md + - README.md workflow_dispatch: {} concurrency: group: pages cancel-in-progress: true jobs: + link-check: + name: Check broken links + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - name: Setup Node.js + uses: actions/setup-node@49933ea5288caeca8642195f572a2b2b8a0a4b70 # v4.4.0 + with: + node-version: "22" + - name: Install dependencies + run: yarn install --frozen-lockfile + - name: Run markdown link check + run: yarn workspace @abca/docs run link-check build: name: Build documentation + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest permissions: contents: read diff --git a/docs/.markdown-link-check.json b/docs/.markdown-link-check.json new file mode 100644 index 00000000..b005608d --- /dev/null +++ b/docs/.markdown-link-check.json @@ -0,0 +1,24 @@ +{ + "ignorePatterns": [ + { "pattern": "^https?://localhost" }, + { "pattern": "^https?://127\\.0\\.0\\.1" }, + { "pattern": "^https?://example\\.com" }, + { "pattern": "^https?://www\\.npmjs\\.com" }, + { "pattern": "^/sample-autonomous-cloud-coding-agents/" }, + { "pattern": "^link$" }, + { "pattern": "github\\.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/bootstrap" } + ], + "replacementPatterns": [ + { "pattern": "^/", "replacement": "{{BASEURL}}/" } + ], + "httpHeaders": [ + { + "urls": ["https://github.com"], + "headers": { "Accept": "text/html" } + } + ], + "retryOn429": true, + "retryCount": 3, + "fallbackRetryDelay": "10s", + "aliveStatusCodes": [200, 206, 301, 302, 307, 308] +} diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md index 6b4e6e0c..a76f5cc5 100644 --- a/docs/guides/DEVELOPER_GUIDE.md +++ b/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 pull requests that touch documentation. diff --git a/docs/mise.toml b/docs/mise.toml index 50a3a0cd..c8597c81 100644 --- a/docs/mise.toml +++ b/docs/mise.toml @@ -24,3 +24,10 @@ 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] +description = "Check for broken links in Markdown sources" +run = """ +find guides design decisions .. -maxdepth 1 -name '*.md' | \ + xargs ./node_modules/.bin/markdown-link-check --config .markdown-link-check.json +""" diff --git a/docs/package.json b/docs/package.json index 50e0640b..d4095802 100644 --- a/docs/package.json +++ b/docs/package.json @@ -8,11 +8,13 @@ "docs:build": "npm run sync && astro build", "build": "npm run docs:build", "preview": "astro preview", - "security:retire": "retire --path . --severity high" + "security:retire": "retire --path . --severity high", + "link-check": "find ../docs/guides ../docs/design ../docs/decisions .. -maxdepth 1 -name '*.md' | xargs markdown-link-check --config .markdown-link-check.json" }, "devDependencies": { "jest": "^30.3.0", "jest-junit": "^16", + "markdown-link-check": "^3.13.6", "retire": "^5.4.2" }, "dependencies": { diff --git a/docs/src/content/docs/developer-guide/Project-structure.md b/docs/src/content/docs/developer-guide/Project-structure.md index 3a520acf..5a4dc940 100644 --- a/docs/src/content/docs/developer-guide/Project-structure.md +++ b/docs/src/content/docs/developer-guide/Project-structure.md @@ -83,4 +83,6 @@ Source docs live in `docs/guides/` and `docs/design/`. The Starlight site under | Change the sidebar or site config | `docs/astro.config.mjs` | | 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. \ No newline at end of file +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 pull requests that touch documentation. \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index 053b4b80..d5af726a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3786,6 +3786,35 @@ resolved "https://registry.yarnpkg.com/@nodable/entities/-/entities-2.1.0.tgz#f543e5c6446720d4cf9e498a83019dd159973bc2" integrity sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA== +"@oozcitak/dom@^2.0.2": + version "2.0.2" + resolved "https://registry.yarnpkg.com/@oozcitak/dom/-/dom-2.0.2.tgz#0f447f0b736aa6f36c5556ba811a44e56c71c26c" + integrity sha512-GjpKhkSYC3Mj4+lfwEyI1dqnsKTgwGy48ytZEhm4A/xnH/8z9M3ZVXKr/YGQi3uCLs1AEBS+x5T2JPiueEDW8w== + dependencies: + "@oozcitak/infra" "^2.0.2" + "@oozcitak/url" "^3.0.0" + "@oozcitak/util" "^10.0.0" + +"@oozcitak/infra@^2.0.2": + version "2.0.2" + resolved "https://registry.yarnpkg.com/@oozcitak/infra/-/infra-2.0.2.tgz#e2f1cc0eeca3ac5cd551f0326a5f66f00cf1138b" + integrity sha512-2g+E7hoE2dgCz/APPOEK5s3rMhJvNxSMBrP+U+j1OWsIbtSpWxxlUjq1lU8RIsFJNYv7NMlnVsCuHcUzJW+8vA== + dependencies: + "@oozcitak/util" "^10.0.0" + +"@oozcitak/url@^3.0.0": + version "3.0.0" + resolved "https://registry.yarnpkg.com/@oozcitak/url/-/url-3.0.0.tgz#a03c959c67e28aba9e29b2d35cd50d26cb5f2cc4" + integrity sha512-ZKfET8Ak1wsLAiLWNfFkZc/BraDccuTJKR6svTYc7sVjbR+Iu0vtXdiDMY4o6jaFl5TW2TlS7jbLl4VovtAJWQ== + dependencies: + "@oozcitak/infra" "^2.0.2" + "@oozcitak/util" "^10.0.0" + +"@oozcitak/util@^10.0.0": + version "10.0.0" + resolved "https://registry.yarnpkg.com/@oozcitak/util/-/util-10.0.0.tgz#f6b40472d96c210094a556ee5ccb8e77f1bd30af" + integrity sha512-hAX0pT/73190NLqBPPWSdBVGtbY6VOhWYK3qqHqtXQ1gK7kS2yz4+ivsN07hpJ6I3aeMtKP6J6npsEKOAzuTLA== + "@oslojs/encoding@^1.1.0": version "1.1.0" resolved "https://registry.yarnpkg.com/@oslojs/encoding/-/encoding-1.1.0.tgz#55f3d9a597430a01f2a5ef63c6b42f769f9ce34e" @@ -6277,6 +6306,11 @@ astronomical@^3.0.0: dependencies: meriyah "^6.0.3" +async@^3.2.6: + version "3.2.6" + resolved "https://registry.yarnpkg.com/async/-/async-3.2.6.tgz#1b0728e14929d51b85b449b7f06e27c1145e38ce" + integrity sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA== + aws-cdk-lib@^2.257.0: version "2.257.0" resolved "https://registry.yarnpkg.com/aws-cdk-lib/-/aws-cdk-lib-2.257.0.tgz#0354efdbc7a236e5e4ca5c3288e71ee4a766da0a" @@ -6512,6 +6546,11 @@ chalk@^4.1.2: ansi-styles "^4.1.0" supports-color "^7.1.0" +chalk@^5.6.2: + version "5.6.2" + resolved "https://registry.yarnpkg.com/chalk/-/chalk-5.6.2.tgz#b1238b6e23ea337af71c7f8a295db5af0c158aea" + integrity sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA== + char-regex@^1.0.2: version "1.0.2" resolved "https://registry.yarnpkg.com/char-regex/-/char-regex-1.0.2.tgz#d744358226217f981ed58f479b1d6bcc29545dcf" @@ -6537,6 +6576,35 @@ character-reference-invalid@^2.0.0: resolved "https://registry.yarnpkg.com/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz#85c66b041e43b47210faf401278abf808ac45cb9" integrity sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw== +cheerio-select@^2.1.0: + version "2.1.0" + resolved "https://registry.yarnpkg.com/cheerio-select/-/cheerio-select-2.1.0.tgz#4d8673286b8126ca2a8e42740d5e3c4884ae21b4" + integrity sha512-9v9kG0LvzrlcungtnJtpGNxY+fzECQKhK4EGJX2vByejiMX84MFNQw4UxPJl3bFbTMw+Dfs37XaIkCwTZfLh4g== + dependencies: + boolbase "^1.0.0" + css-select "^5.1.0" + css-what "^6.1.0" + domelementtype "^2.3.0" + domhandler "^5.0.3" + domutils "^3.0.1" + +cheerio@^1.0.0-rc.10: + version "1.2.0" + resolved "https://registry.yarnpkg.com/cheerio/-/cheerio-1.2.0.tgz#f23b777c49021ead7475dcf3390d3535a7f896d6" + integrity sha512-WDrybc/gKFpTYQutKIK6UvfcuxijIZfMfXaYm8NMsPQxSYvf+13fXUJ4rztGGbJcBQ/GF55gvrZ0Bc0bj/mqvg== + dependencies: + cheerio-select "^2.1.0" + dom-serializer "^2.0.0" + domhandler "^5.0.3" + domutils "^3.2.2" + encoding-sniffer "^0.2.1" + htmlparser2 "^10.1.0" + parse5 "^7.3.0" + parse5-htmlparser2-tree-adapter "^7.1.0" + parse5-parser-stream "^7.1.2" + undici "^7.19.0" + whatwg-mimetype "^4.0.0" + chokidar@^4.0.3: version "4.0.3" resolved "https://registry.yarnpkg.com/chokidar/-/chokidar-4.0.3.tgz#7be37a4c03c9aee1ecfe862a4a23b2c70c205d30" @@ -6617,7 +6685,7 @@ commander@^11.1.0: resolved "https://registry.yarnpkg.com/commander/-/commander-11.1.0.tgz#62fdce76006a68e5c1ab3314dc92e800eb83d906" integrity sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ== -commander@^14.0.3: +commander@^14.0.2, commander@^14.0.3: version "14.0.3" resolved "https://registry.yarnpkg.com/commander/-/commander-14.0.3.tgz#425d79b48f9af82fcd9e4fc1ea8af6c5ec07bbc2" integrity sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw== @@ -6853,7 +6921,7 @@ domhandler@^5.0.2, domhandler@^5.0.3: dependencies: domelementtype "^2.3.0" -domutils@^3.0.1: +domutils@^3.0.1, domutils@^3.2.2: version "3.2.2" resolved "https://registry.yarnpkg.com/domutils/-/domutils-3.2.2.tgz#edbfe2b668b0c1d97c24baf0f1062b132221bc78" integrity sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw== @@ -6900,6 +6968,14 @@ emoji-regex@^9.2.2: resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-9.2.2.tgz#840c8803b0d8047f4ff0cf963176b32d4ef3ed72" integrity sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg== +encoding-sniffer@^0.2.1: + version "0.2.1" + resolved "https://registry.yarnpkg.com/encoding-sniffer/-/encoding-sniffer-0.2.1.tgz#396ec97ac22ce5a037ba44af1992ac9d46a7b819" + integrity sha512-5gvq20T6vfpekVtqrYQsSCFZ1wEg5+wW0/QaZMWkFr6BqD3NfKs0rLCx4rrVlSWJeZb5NBJgVLswK/w2MWU+Gw== + dependencies: + iconv-lite "^0.6.3" + whatwg-encoding "^3.1.1" + entities@^4.2.0: version "4.5.0" resolved "https://registry.yarnpkg.com/entities/-/entities-4.5.0.tgz#5d268ea5e7113ec74c4d033b79ea5a35a488fb48" @@ -6910,6 +6986,11 @@ entities@^6.0.0: resolved "https://registry.yarnpkg.com/entities/-/entities-6.0.1.tgz#c28c34a43379ca7f61d074130b2f5f7020a30694" integrity sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g== +entities@^7.0.1: + version "7.0.1" + resolved "https://registry.yarnpkg.com/entities/-/entities-7.0.1.tgz#26e8a88889db63417dcb9a1e79a3f1bc92b5976b" + integrity sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA== + error-ex@^1.3.1: version "1.3.4" resolved "https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.4.tgz#b3a8d8bb6f92eecc1629e3e27d3c8607a8a32414" @@ -7825,6 +7906,13 @@ html-escaper@^2.0.0: resolved "https://registry.yarnpkg.com/html-escaper/-/html-escaper-2.0.2.tgz#dfd60027da36a36dfcbe236262c00a5822681453" integrity sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg== +html-link-extractor@^1.0.5: + version "1.0.5" + resolved "https://registry.yarnpkg.com/html-link-extractor/-/html-link-extractor-1.0.5.tgz#a4be345cb13b8c3352d82b28c8b124bb7bf5dd6f" + integrity sha512-ADd49pudM157uWHwHQPUSX4ssMsvR/yHIswOR5CUfBdK9g9ZYGMhVSE6KZVHJ6kCkR0gH4htsfzU6zECDNVwyw== + dependencies: + cheerio "^1.0.0-rc.10" + html-void-elements@^3.0.0: version "3.0.0" resolved "https://registry.yarnpkg.com/html-void-elements/-/html-void-elements-3.0.0.tgz#fc9dbd84af9e747249034d4d62602def6517f1d7" @@ -7835,6 +7923,16 @@ html-whitespace-sensitive-tag-names@^3.0.0: resolved "https://registry.yarnpkg.com/html-whitespace-sensitive-tag-names/-/html-whitespace-sensitive-tag-names-3.0.1.tgz#c35edd28205f3bf8c1fd03274608d60b923de5b2" integrity sha512-q+310vW8zmymYHALr1da4HyXUQ0zgiIwIicEfotYPWGN0OJVEN/58IJ3A4GBYcEq3LGAZqKb+ugvP0GNB9CEAA== +htmlparser2@^10.1.0: + version "10.1.0" + resolved "https://registry.yarnpkg.com/htmlparser2/-/htmlparser2-10.1.0.tgz#fe3f2e12c73b6e462d4e10395db9c1119e4d6ae4" + integrity sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ== + dependencies: + domelementtype "^2.3.0" + domhandler "^5.0.3" + domutils "^3.2.2" + entities "^7.0.1" + http-cache-semantics@^4.2.0: version "4.2.0" resolved "https://registry.yarnpkg.com/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz#205f4db64f8562b76a4ff9235aa5279839a09dd5" @@ -7868,6 +7966,13 @@ i18next@^23.11.5: dependencies: "@babel/runtime" "^7.23.2" +iconv-lite@0.6.3, iconv-lite@^0.6.3: + version "0.6.3" + resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.6.3.tgz#a52f80bf38da1952eb5c681790719871a1a72501" + integrity sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw== + dependencies: + safer-buffer ">= 2.1.2 < 3.0.0" + ignore@^5.2.0, ignore@^5.3.2: version "5.3.2" resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.3.2.tgz#3cd40e729f3643fd87cb04e50bf0eb722bc596f5" @@ -7919,6 +8024,11 @@ iron-webcrypto@^1.2.1: resolved "https://registry.yarnpkg.com/iron-webcrypto/-/iron-webcrypto-1.2.1.tgz#aa60ff2aa10550630f4c0b11fd2442becdb35a6f" integrity sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg== +is-absolute-url@^4.0.1: + version "4.0.1" + resolved "https://registry.yarnpkg.com/is-absolute-url/-/is-absolute-url-4.0.1.tgz#16e4d487d4fded05cfe0685e53ec86804a5e94dc" + integrity sha512-/51/TKE88Lmm7Gc4/8btclNXWS+g50wXhYJq8HWIBAGUBnoAdRu1aXeh364t/O7wXDAcTJDP8PNuNKWUDWie+A== + is-alphabetical@^2.0.0: version "2.0.1" resolved "https://registry.yarnpkg.com/is-alphabetical/-/is-alphabetical-2.0.1.tgz#01072053ea7c1036df3c7d19a6daaec7f19e789b" @@ -7998,6 +8108,13 @@ is-plain-obj@^4.0.0: resolved "https://registry.yarnpkg.com/is-plain-obj/-/is-plain-obj-4.1.0.tgz#d65025edec3657ce032fd7db63c97883eaed71f0" integrity sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg== +is-relative-url@^4.1.0: + version "4.1.0" + resolved "https://registry.yarnpkg.com/is-relative-url/-/is-relative-url-4.1.0.tgz#fe8efb2616b272cf141d3c9de9760594e53453a7" + integrity sha512-vhIXKasjAuxS7n+sdv7pJQykEAgS+YU8VBQOENXwo/VZpOHDgBBsIbHo7zFKaWBjYWF4qxERdhbPRRtFAeJKfg== + dependencies: + is-absolute-url "^4.0.1" + is-stream@^2.0.0: version "2.0.1" resolved "https://registry.yarnpkg.com/is-stream/-/is-stream-2.0.1.tgz#fac1e3d53b97ad5a9d0ae9cef2389f5810a5c077" @@ -8550,6 +8667,17 @@ lines-and-columns@^1.1.6: resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.2.4.tgz#eca284f75d2965079309dc0ad9255abb2ebc1632" integrity sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg== +link-check@^5.5.1: + version "5.5.1" + resolved "https://registry.yarnpkg.com/link-check/-/link-check-5.5.1.tgz#f172096584a7ed43a8936a8d5869a43a877be6a0" + integrity sha512-GrtE4Zp/FBduvElmad375NrPeMYnKwNt9rH/TDG/rbQbHL0QVC4S/cEPVKZ0CkhXlVuiK+/5flGpRxQzoLbjEA== + dependencies: + is-relative-url "^4.1.0" + ms "^2.1.3" + needle "^3.3.1" + node-email-verifier "^3.4.1" + proxy-agent "^6.5.0" + locate-path@^5.0.0: version "5.0.0" resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-5.0.0.tgz#1afba396afd676a6d42504d0a67a3a7eb9f62aa0" @@ -8641,11 +8769,39 @@ markdown-extensions@^2.0.0: resolved "https://registry.yarnpkg.com/markdown-extensions/-/markdown-extensions-2.0.0.tgz#34bebc83e9938cae16e0e017e4a9814a8330d3c4" integrity sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q== +markdown-link-check@^3.13.6: + version "3.14.2" + resolved "https://registry.yarnpkg.com/markdown-link-check/-/markdown-link-check-3.14.2.tgz#5683dfb039d8c658117a3950f4faac9c6774e0f8" + integrity sha512-DPJ+itd3D5fcfXD5s1i53lugH0Z/h80kkQxlYCBh8tFwEZGhyVgDcLl0rnKlWssAVDAmSmcbePpHpMEY+JcMMQ== + dependencies: + async "^3.2.6" + chalk "^5.6.2" + commander "^14.0.2" + link-check "^5.5.1" + markdown-link-extractor "^4.0.3" + needle "^3.3.1" + progress "^2.0.3" + proxy-agent "^6.5.0" + xmlbuilder2 "^4.0.0" + +markdown-link-extractor@^4.0.3: + version "4.0.3" + resolved "https://registry.yarnpkg.com/markdown-link-extractor/-/markdown-link-extractor-4.0.3.tgz#4bca0255c583f017b1f0ce857d5a1af56af99ac4" + integrity sha512-aEltJiQ4/oC0h6Jbw/uuATGSHZPkcH8DIunNH1A0e+GSFkvZ6BbBkdvBTVfIV8r6HapCU3yTd0eFdi3ZeM1eAQ== + dependencies: + html-link-extractor "^1.0.5" + marked "^17.0.0" + markdown-table@^3.0.0: version "3.0.4" resolved "https://registry.yarnpkg.com/markdown-table/-/markdown-table-3.0.4.tgz#fe44d6d410ff9d6f2ea1797a3f60aa4d2b631c2a" integrity sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw== +marked@^17.0.0: + version "17.0.6" + resolved "https://registry.yarnpkg.com/marked/-/marked-17.0.6.tgz#2a97586a272d3be5880f198e020b74ad27cf86ba" + integrity sha512-gB0gkNafnonOw0obSTEGZTT86IuhILt2Wfx0mWH/1Au83kybTayroZ/V6nS25mN7u8ASy+5fMhgB3XPNrOZdmA== + mdast-util-definitions@^6.0.0: version "6.0.0" resolved "https://registry.yarnpkg.com/mdast-util-definitions/-/mdast-util-definitions-6.0.0.tgz#c1bb706e5e76bb93f9a09dd7af174002ae69ac24" @@ -9351,6 +9507,14 @@ natural-compare@^1.4.0: resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7" integrity sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw== +needle@^3.3.1: + version "3.5.0" + resolved "https://registry.yarnpkg.com/needle/-/needle-3.5.0.tgz#aa2023642cb41b11a11babb733fd8fa952919112" + integrity sha512-jaQyPKKk2YokHrEg+vFDYxXIHTCBgiZwSHOoVx/8V3GIBS8/VN6NdVRmg8q1ERtPkMvmOvebsgga4sAj5hls/w== + dependencies: + iconv-lite "^0.6.3" + sax "^1.2.4" + neo-async@^2.6.2: version "2.6.2" resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f" @@ -9373,6 +9537,14 @@ nlcst-to-string@^4.0.0: dependencies: "@types/nlcst" "^2.0.0" +node-email-verifier@^3.4.1: + version "3.4.1" + resolved "https://registry.yarnpkg.com/node-email-verifier/-/node-email-verifier-3.4.1.tgz#08d445a47af34e33332447489bc0360ce55f8019" + integrity sha512-69JMeWgEUrCji+dOLULirdSoosRxgAq2y+imfmHHBGvgTwyTKqvm65Ls3+W30DCIWMrYj5kKVb/DHTQDK7OVwQ== + dependencies: + ms "^2.1.3" + validator "^13.15.15" + node-ensure@^0.0.0: version "0.0.0" resolved "https://registry.yarnpkg.com/node-ensure/-/node-ensure-0.0.0.tgz#ecae764150de99861ec5c810fd5d096b183932a7" @@ -9630,7 +9802,22 @@ parse-statements@1.0.11: resolved "https://registry.yarnpkg.com/parse-statements/-/parse-statements-1.0.11.tgz#8787c5d383ae5746568571614be72b0689584344" integrity sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA== -parse5@^7.0.0: +parse5-htmlparser2-tree-adapter@^7.1.0: + version "7.1.0" + resolved "https://registry.yarnpkg.com/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-7.1.0.tgz#b5a806548ed893a43e24ccb42fbb78069311e81b" + integrity sha512-ruw5xyKs6lrpo9x9rCZqZZnIUntICjQAd0Wsmp396Ul9lN/h+ifgVV1x1gZHi8euej6wTfpqX8j+BFQxF0NS/g== + dependencies: + domhandler "^5.0.3" + parse5 "^7.0.0" + +parse5-parser-stream@^7.1.2: + version "7.1.2" + resolved "https://registry.yarnpkg.com/parse5-parser-stream/-/parse5-parser-stream-7.1.2.tgz#d7c20eadc37968d272e2c02660fff92dd27e60e1" + integrity sha512-JyeQc9iwFLn5TbvvqACIF/VXG6abODeB3Fwmv/TGdLk2LfbWkaySGY72at4+Ty7EkPZj854u4CrICqNk2qIbow== + dependencies: + parse5 "^7.0.0" + +parse5@^7.0.0, parse5@^7.3.0: version "7.3.0" resolved "https://registry.yarnpkg.com/parse5/-/parse5-7.3.0.tgz#d7e224fa72399c7a175099f45fc2ad024b05ec05" integrity sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw== @@ -9757,12 +9944,17 @@ prismjs@^1.30.0: resolved "https://registry.yarnpkg.com/prismjs/-/prismjs-1.30.0.tgz#d9709969d9d4e16403f6f348c63553b19f0975a9" integrity sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw== +progress@^2.0.3: + version "2.0.3" + resolved "https://registry.yarnpkg.com/progress/-/progress-2.0.3.tgz#7e8cf8d8f5b8f239c1bc68beb4eb78567d572ef8" + integrity sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA== + property-information@^7.0.0: version "7.1.0" resolved "https://registry.yarnpkg.com/property-information/-/property-information-7.1.0.tgz#b622e8646e02b580205415586b40804d3e8bfd5d" integrity sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ== -proxy-agent@^6.4.0: +proxy-agent@^6.4.0, proxy-agent@^6.5.0: version "6.5.0" resolved "https://registry.yarnpkg.com/proxy-agent/-/proxy-agent-6.5.0.tgz#9e49acba8e4ee234aacb539f89ed9c23d02f232d" integrity sha512-TmatMXdr2KlRiA2CyDu8GqR8EjahTG3aY3nXjdzFyoZbmB8hrBsTyMezhULIXKnC0jpfjlmiZ3+EaCzoInSu/A== @@ -10132,7 +10324,12 @@ rollup@^4.43.0: "@rollup/rollup-win32-x64-msvc" "4.60.1" fsevents "~2.3.2" -sax@^1.4.1, sax@^1.5.0: +"safer-buffer@>= 2.1.2 < 3.0.0": + version "2.1.2" + resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a" + integrity sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg== + +sax@^1.2.4, sax@^1.4.1, sax@^1.5.0: version "1.6.0" resolved "https://registry.yarnpkg.com/sax/-/sax-1.6.0.tgz#da59637629307b97e7c4cb28e080a7bc38560d5b" integrity sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA== @@ -10699,6 +10896,11 @@ undici-types@~7.18.0: resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-7.18.2.tgz#29357a89e7b7ca4aef3bf0fd3fd0cd73884229e9" integrity sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w== +undici@^7.19.0: + version "7.27.2" + resolved "https://registry.yarnpkg.com/undici/-/undici-7.27.2.tgz#f8fae968ee68377cfc61713d9cd152773716804f" + integrity sha512-uZsKNuzQxDMUY6M3pIMvy5tvlGmtq8XJ2oLAkfRKGNu+1VQAIvLy2xIVG5ATZl5wDXl/tddByAWCizRbOme+TA== + unified@^11.0.0, unified@^11.0.4, unified@^11.0.5: version "11.0.5" resolved "https://registry.yarnpkg.com/unified/-/unified-11.0.5.tgz#f66677610a5c0a9ee90cab2b8d4d66037026d9e1" @@ -10912,6 +11114,11 @@ v8-to-istanbul@^9.0.1: "@types/istanbul-lib-coverage" "^2.0.1" convert-source-map "^2.0.0" +validator@^13.15.15: + version "13.15.35" + resolved "https://registry.yarnpkg.com/validator/-/validator-13.15.35.tgz#81cf455c51f15b69d8d340be5914f3fab00dbf7f" + integrity sha512-TQ5pAGhd5whStmqWvYF4OjQROlmv9SMFVt37qoCBdqRffuuklWYQlCNnEs2ZaIBD1kZRNnikiZOS1eqgkar0iw== + vfile-location@^5.0.0: version "5.0.3" resolved "https://registry.yarnpkg.com/vfile-location/-/vfile-location-5.0.3.tgz#cb9eacd20f2b6426d19451e0eafa3d0a846225c3" @@ -11105,6 +11312,18 @@ web-namespaces@^2.0.0: resolved "https://registry.yarnpkg.com/web-namespaces/-/web-namespaces-2.0.1.tgz#1010ff7c650eccb2592cebeeaf9a1b253fd40692" integrity sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ== +whatwg-encoding@^3.1.1: + version "3.1.1" + resolved "https://registry.yarnpkg.com/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz#d0f4ef769905d426e1688f3e34381a99b60b76e5" + integrity sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ== + dependencies: + iconv-lite "0.6.3" + +whatwg-mimetype@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz#bc1bf94a985dc50388d54a9258ac405c3ca2fc0a" + integrity sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg== + which-pm-runs@^1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/which-pm-runs/-/which-pm-runs-1.1.0.tgz#35ccf7b1a0fce87bd8b92a478c9d045785d3bf35" @@ -11177,6 +11396,16 @@ xml@^1.0.1: resolved "https://registry.yarnpkg.com/xml/-/xml-1.0.1.tgz#78ba72020029c5bc87b8a81a3cfcd74b4a2fc1e5" integrity sha512-huCv9IH9Tcf95zuYCsQraZtWnJvBtLVE0QHMOs8bWyZAFZNDcYjsPq1nEx8jKA9y+Beo9v+7OBPRisQTjinQMw== +xmlbuilder2@^4.0.0: + version "4.0.3" + resolved "https://registry.yarnpkg.com/xmlbuilder2/-/xmlbuilder2-4.0.3.tgz#91660fa6d30f19d716f8b1194c567686d4402c63" + integrity sha512-bx8Q1STctnNaaDymWnkfQLKofs0mGNN7rLLapJlGuV3VlvegD7Ls4ggMjE3aUSWItCCzU0PEv45lI87iSigiCA== + dependencies: + "@oozcitak/dom" "^2.0.2" + "@oozcitak/infra" "^2.0.2" + "@oozcitak/util" "^10.0.0" + js-yaml "^4.1.1" + xxhash-wasm@^1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/xxhash-wasm/-/xxhash-wasm-1.1.0.tgz#ffe7f0b98220a4afac171e3fb9b6d1f8771f015e" From c3736fdd982254a82a804b687f5c74d4d3c2bf80 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 10 Jun 2026 08:59:41 -0400 Subject: [PATCH 2/7] fix(ci): use correct actions/setup-node SHA (v6.4.0) --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f1d3183c..e8fa196c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -36,7 +36,7 @@ jobs: with: persist-credentials: false - name: Setup Node.js - uses: actions/setup-node@49933ea5288caeca8642195f572a2b2b8a0a4b70 # v4.4.0 + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 with: node-version: "22" - name: Install dependencies From 3a013d736e6c0923d2ed2c15987112b81aba4491 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 10 Jun 2026 09:04:26 -0400 Subject: [PATCH 3/7] fix(docs): correct broken anchor in WORKFLOWS.md The link #domain--requiresrepo was missing the underscore; the heading renders as #domain--requires_repo. --- docs/design/WORKFLOWS.md | 2 +- docs/src/content/docs/architecture/Workflows.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design/WORKFLOWS.md b/docs/design/WORKFLOWS.md index 4a992958..3492f2c6 100644 --- a/docs/design/WORKFLOWS.md +++ b/docs/design/WORKFLOWS.md @@ -474,7 +474,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 diff --git a/docs/src/content/docs/architecture/Workflows.md b/docs/src/content/docs/architecture/Workflows.md index 6c66aa76..0fc26319 100644 --- a/docs/src/content/docs/architecture/Workflows.md +++ b/docs/src/content/docs/architecture/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](/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 From 5accd77dd3e30fb1e48cf63d995ec45dadbc0e77 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 10 Jun 2026 14:13:18 -0400 Subject: [PATCH 4/7] =?UTF-8?q?fix(docs):=20address=20PR=20review=20?= =?UTF-8?q?=E2=80=94=20harden=20link-check=20and=20wire=20into=20drift-pre?= =?UTF-8?q?vention?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .github/workflows/docs.yml | 29 ------------------- docs/.markdown-link-check.json | 7 ++--- ...-002-least-privilege-bootstrap-policies.md | 2 +- docs/mise.toml | 13 +++++++-- docs/package.json | 2 +- mise.toml | 1 + 6 files changed, 17 insertions(+), 37 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e8fa196c..0687ff55 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -10,42 +10,13 @@ on: - docs/scripts/** - .github/workflows/docs.yml - CONTRIBUTING.md - pull_request: - paths: - - docs/** - - docs/guides/** - - docs/design/** - - docs/decisions/** - - .github/workflows/docs.yml - - CONTRIBUTING.md - - AGENTS.md - - README.md workflow_dispatch: {} concurrency: group: pages cancel-in-progress: true jobs: - link-check: - name: Check broken links - runs-on: ubuntu-latest - permissions: - contents: read - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - persist-credentials: false - - name: Setup Node.js - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 - with: - node-version: "22" - - name: Install dependencies - run: yarn install --frozen-lockfile - - name: Run markdown link check - run: yarn workspace @abca/docs run link-check build: name: Build documentation - if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest permissions: contents: read diff --git a/docs/.markdown-link-check.json b/docs/.markdown-link-check.json index b005608d..1c092653 100644 --- a/docs/.markdown-link-check.json +++ b/docs/.markdown-link-check.json @@ -3,10 +3,9 @@ { "pattern": "^https?://localhost" }, { "pattern": "^https?://127\\.0\\.0\\.1" }, { "pattern": "^https?://example\\.com" }, - { "pattern": "^https?://www\\.npmjs\\.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$" }, - { "pattern": "github\\.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/bootstrap" } + { "pattern": "^link$", "_comment": "Masks intentional placeholder in ADR-004 example prose" } ], "replacementPatterns": [ { "pattern": "^/", "replacement": "{{BASEURL}}/" } @@ -20,5 +19,5 @@ "retryOn429": true, "retryCount": 3, "fallbackRetryDelay": "10s", - "aliveStatusCodes": [200, 206, 301, 302, 307, 308] + "aliveStatusCodes": [200, 206] } diff --git a/docs/decisions/ADR-002-least-privilege-bootstrap-policies.md b/docs/decisions/ADR-002-least-privilege-bootstrap-policies.md index 553ca261..398403fc 100644 --- a/docs/decisions/ADR-002-least-privilege-bootstrap-policies.md +++ b/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) diff --git a/docs/mise.toml b/docs/mise.toml index c8597c81..f40c77ca 100644 --- a/docs/mise.toml +++ b/docs/mise.toml @@ -28,6 +28,15 @@ run = "./node_modules/.bin/astro sync && ./node_modules/.bin/astro check" [tasks.link-check] description = "Check for broken links in Markdown sources" run = """ -find guides design decisions .. -maxdepth 1 -name '*.md' | \ - xargs ./node_modules/.bin/markdown-link-check --config .markdown-link-check.json +#!/usr/bin/env bash +set -euo pipefail +filelist=$(mktemp) +trap 'rm -f "$filelist"' EXIT +{ find guides design decisions -name '*.md'; find .. -maxdepth 1 -name '*.md'; } > "$filelist" +count=$(wc -l < "$filelist") +if [ "$count" -lt 10 ]; then + echo "ERROR: expected ≥10 Markdown files but found $count — scan may be misconfigured" >&2 + exit 1 +fi +xargs -r ./node_modules/.bin/markdown-link-check --config .markdown-link-check.json < "$filelist" """ diff --git a/docs/package.json b/docs/package.json index d4095802..1c57d91b 100644 --- a/docs/package.json +++ b/docs/package.json @@ -9,7 +9,7 @@ "build": "npm run docs:build", "preview": "astro preview", "security:retire": "retire --path . --severity high", - "link-check": "find ../docs/guides ../docs/design ../docs/decisions .. -maxdepth 1 -name '*.md' | xargs markdown-link-check --config .markdown-link-check.json" + "link-check": "mise run link-check" }, "devDependencies": { "jest": "^30.3.0", diff --git a/mise.toml b/mise.toml index 6f5f351b..c1c9669b 100644 --- a/mise.toml +++ b/mise.toml @@ -77,6 +77,7 @@ run = [ { task = "check:constants-sync" }, { task = "check:types-sync" }, { task = "check:coverage-thresholds-sync" }, + { task = "//docs:link-check" }, ] ################## From 675c5d1de0342d1e36c41a9f5b944001f2e09be8 Mon Sep 17 00:00:00 2001 From: bgagent Date: Wed, 10 Jun 2026 14:43:12 -0400 Subject: [PATCH 5/7] fix(docs): regenerate Starlight mirror for ADR-002 link update --- .../decisions/Adr-002-least-privilege-bootstrap-policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/decisions/Adr-002-least-privilege-bootstrap-policies.md b/docs/src/content/docs/decisions/Adr-002-least-privilege-bootstrap-policies.md index 8255f458..3dd413ff 100644 --- a/docs/src/content/docs/decisions/Adr-002-least-privilege-bootstrap-policies.md +++ b/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) From 513baf4b0c2105e86bc2d99a956e57b282c26367 Mon Sep 17 00:00:00 2001 From: bgagent Date: Thu, 11 Jun 2026 09:28:38 -0400 Subject: [PATCH 6/7] 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. --- docs/guides/DEVELOPER_GUIDE.md | 2 +- docs/src/content/docs/developer-guide/Project-structure.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md index a76f5cc5..a1e765e6 100644 --- a/docs/guides/DEVELOPER_GUIDE.md +++ b/docs/guides/DEVELOPER_GUIDE.md @@ -374,4 +374,4 @@ Source docs live in `docs/guides/` and `docs/design/`. The Starlight site under 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 pull requests that touch documentation. +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. diff --git a/docs/src/content/docs/developer-guide/Project-structure.md b/docs/src/content/docs/developer-guide/Project-structure.md index 5a4dc940..566b0340 100644 --- a/docs/src/content/docs/developer-guide/Project-structure.md +++ b/docs/src/content/docs/developer-guide/Project-structure.md @@ -85,4 +85,4 @@ Source docs live in `docs/guides/` and `docs/design/`. The Starlight site under 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 pull requests that touch documentation. \ No newline at end of file +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. \ No newline at end of file From 39f8ce5e396d65a55771f60469690ceb2cc3e89f Mon Sep 17 00:00:00 2001 From: bgagent Date: Thu, 11 Jun 2026 09:39:55 -0400 Subject: [PATCH 7/7] 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 --- docs/.markdown-link-check.json | 3 --- docs/mise.toml | 8 +++++--- mise.toml | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/.markdown-link-check.json b/docs/.markdown-link-check.json index 1c092653..34085a08 100644 --- a/docs/.markdown-link-check.json +++ b/docs/.markdown-link-check.json @@ -7,9 +7,6 @@ { "pattern": "^/sample-autonomous-cloud-coding-agents/" }, { "pattern": "^link$", "_comment": "Masks intentional placeholder in ADR-004 example prose" } ], - "replacementPatterns": [ - { "pattern": "^/", "replacement": "{{BASEURL}}/" } - ], "httpHeaders": [ { "urls": ["https://github.com"], diff --git a/docs/mise.toml b/docs/mise.toml index f40c77ca..e9e6867e 100644 --- a/docs/mise.toml +++ b/docs/mise.toml @@ -26,17 +26,19 @@ 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'; find .. -maxdepth 1 -name '*.md'; } > "$filelist" -count=$(wc -l < "$filelist") +{ 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 -r ./node_modules/.bin/markdown-link-check --config .markdown-link-check.json < "$filelist" +xargs -0 -r ./node_modules/.bin/markdown-link-check --config .markdown-link-check.json < "$filelist" """ diff --git a/mise.toml b/mise.toml index 3e63a356..7b89c775 100644 --- a/mise.toml +++ b/mise.toml @@ -89,7 +89,7 @@ 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" },