From bcb4355c3689702c763ce64c253dcaa4753df18a Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 5 Jun 2026 12:52:50 -0400
Subject: [PATCH] docs: move blessed aws-cdk-lib pin to 2.257.0 (#10)

2.253.1 bundles fast-uri 3.1.0 (two high-severity GHSAs, unfixable via
overrides since it ships in the tarball). 2.257.0 bundles patched
fast-uri 3.1.2 and passes npm ci (the 2.254.0 breakage that motivated
the old pin was release-specific).
---
 aws-infrastructure.md | 4 ++--
 cdk-project-layout.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/aws-infrastructure.md b/aws-infrastructure.md
index e63c734..8d76ad0 100644
--- a/aws-infrastructure.md
+++ b/aws-infrastructure.md
@@ -22,9 +22,9 @@ Never rely on the CloudWatch default for log retention. Always set `RetentionInD
 
 ## CDK Version Policy
 
-Pin `aws-cdk-lib` to a known-good version. The current blessed version is **2.253.1**.
+Pin `aws-cdk-lib` to a known-good version. The current blessed version is **2.257.0**.
 
-Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors. npm `overrides` cannot fix bundled deps. Always test `npm ci` locally before pushing a version bump.
+Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors, and bundled deps can carry vulnerabilities that npm `overrides` cannot fix (e.g., 2.253.1 bundled a high-severity-vulnerable fast-uri; the only remedy is moving to a release that bundles the patched version). When bumping the blessed version: test `npm ci` locally and confirm the new release's bundled deps clear dependency review.
 
 When upgrading, verify on a branch first:
 1. Update `package.json` to the new version
diff --git a/cdk-project-layout.md b/cdk-project-layout.md
index 4a70ba4..484c708 100644
--- a/cdk-project-layout.md
+++ b/cdk-project-layout.md
@@ -83,7 +83,7 @@ A handful of stacks predate this convention and remain PascalCase (e.g., `SeaHav
 
 ## Version Pinning
 
-Pin `aws-cdk-lib` to the blessed version: **2.253.1**.
+Pin `aws-cdk-lib` to the blessed version: **2.257.0**.
 
 `aws-cdk-lib` bundles transitive dependencies (`inBundle: true`). Certain versions break `npm ci` with phantom missing-package errors that cannot be fixed via npm `overrides`. Always test before bumping: