docs(test): correct bundling opt-out to postCliContext (#366)

The documented per-test opt-out used constructor `context`, which CDK
silently overwrites with CDK_CONTEXT_JSON in App.loadContext — so
`new App({ context: { 'aws:cdk:bundling-stacks': ['**'] } })` does NOT
re-enable bundling. Only `postCliContext` (applied last) overrides the
global disable.

Corrects the opt-out instruction and precedence comment in all three
documented locations (disable-bundling.ts, AGENTS.md, review_pr.md).
Verified empirically against aws-cdk-lib@2.257.0. Comment/doc-only;
runtime logic unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: scottschreckengaust

.abca/commands/review_pr.md

@@ -100,8 +100,9 @@ Then apply principal-architect judgment over the diff:
 - **Test performance (CDK synth)** — New/changed CDK tests must not re-enable Lambda bundling at
   synth or synthesize the same stack repeatedly. `cdk/` disables bundling globally via
   `test/setup/disable-bundling.ts` (~15× faster synth); flag any test that turns
-  `aws:cdk:bundling-stacks` back on without asserting on a bundled asset, or that calls
-  `new App()` + `Template.fromStack()` per-test instead of once in `beforeAll`. See
+  `aws:cdk:bundling-stacks` back on (only valid via `postCliContext`, not constructor
+  `context` — the env var overwrites the latter) without asserting on a bundled asset, or
+  that calls `new App()` + `Template.fromStack()` per-test instead of once in `beforeAll`. See
   [CI build performance](../../docs/design/CI_BUILD_PERFORMANCE.md).
 - **Routing** — Changes should land in the right package per the AGENTS.md routing table
   (agent runtime in `agent/`, API/Lambdas in `cdk/`, CLI in `cli/`).

AGENTS.md

@@ -45,7 +45,7 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.
 - Adding or editing files in **`docs/design/`** or **`docs/guides/`** without running **`cd docs && node scripts/sync-starlight.mjs`** — CI will reject ("Fail build on mutation") because the Starlight mirror files in `docs/src/content/docs/` are stale. Always commit the regenerated mirrors alongside source changes.
 - Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.
 - Running raw **`jest`/`tsc`/`cdk`** from muscle memory — prefer **`mise //cdk:test`**, **`mise //cdk:compile`**, **`mise //cdk:synth`** (see [Commands you can use](#commands-you-can-use)).
-- **Bundling Lambda assets in CDK unit tests** — `Template.fromStack()` triggers a full synth that bundles every `NodejsFunction` via esbuild (~28s for `AgentStack`). Unit tests assert on CloudFormation structure, not bundled code, so this is pure overhead. The `cdk/` Jest config disables it globally via `test/setup/disable-bundling.ts` (sets `aws:cdk:bundling-stacks: []` in `CDK_CONTEXT_JSON`), which a bare `new App()` picks up automatically. **Do not re-enable bundling** in a test unless you are specifically asserting on a bundled asset (hash / S3 key) — and if you must, opt out narrowly in that test's `App` context, not globally. Minimize full-stack synths regardless: synthesize each distinct stack config once in `beforeAll` and assert against the cached `Template`. See [CI build performance](./docs/design/CI_BUILD_PERFORMANCE.md) and #366.
+- **Bundling Lambda assets in CDK unit tests** — `Template.fromStack()` triggers a full synth that bundles every `NodejsFunction` via esbuild (~28s for `AgentStack`). Unit tests assert on CloudFormation structure, not bundled code, so this is pure overhead. The `cdk/` Jest config disables it globally via `test/setup/disable-bundling.ts` (sets `aws:cdk:bundling-stacks: []` in `CDK_CONTEXT_JSON`), which a bare `new App()` picks up automatically. **Do not re-enable bundling** in a test unless you are specifically asserting on a bundled asset (hash / S3 key) — and if you must, opt out narrowly via that test's `App` `postCliContext` (e.g. `new App({ postCliContext: { 'aws:cdk:bundling-stacks': ['**'] } })`), not globally. Note that constructor `context` does **not** work for this key: CDK overwrites it with `CDK_CONTEXT_JSON`, so only `postCliContext` (applied last) overrides the global disable. Minimize full-stack synths regardless: synthesize each distinct stack config once in `beforeAll` and assert against the cached `Template`. See [CI build performance](./docs/design/CI_BUILD_PERFORMANCE.md) and #366.
 - **`MISE_EXPERIMENTAL=1`** — required for namespaced tasks like **`mise //cdk:build`** (see [CONTRIBUTING.md](./CONTRIBUTING.md)).
 - **`mise run build`** builds **`//agent:quality`** alongside **`//cdk:build`** (the deployed image bundles **`agent/`**, so agent quality is part of the build) — these run as parallel `depends`, not in a fixed order; agent changes belong in the **`agent/`** tree.
 - **`prek install`** fails if Git **`core.hooksPath`** is set — another hook manager owns hooks; see [CONTRIBUTING.md](./CONTRIBUTING.md).

cdk/test/setup/disable-bundling.ts

@@ -28,11 +28,19 @@
 // `aws:cdk:bundling-stacks: []` tells the CLI/synth to bundle no stacks. CDK
 // reads CDK_CONTEXT_JSON when an `App` is constructed, so a bare `new App()`
 // (the overwhelming-majority pattern in our tests) picks this up with no
-// call-site changes. Tests that pass their own `{ context }` still merge on top.
+// call-site changes.
+//
+// Precedence matters for the opt-out. CDK's `App.loadContext(props.context,
+// props.postCliContext)` applies `props.context` FIRST, then overwrites it with
+// CDK_CONTEXT_JSON, then applies `postCliContext` LAST. So for this key the env
+// var beats constructor `context` — `new App({ context: { 'aws:cdk:bundling-
+// stacks': ['**'] } })` does NOT re-enable bundling (the env var clobbers it).
 //
 // If a test ever needs real bundled assets (e.g. asserting on an asset hash /
-// S3 key), it must opt out by constructing its `App` with
-// `aws:cdk:bundling-stacks: ['**']` (or the specific stack id) in its context.
+// S3 key), it must opt out via `postCliContext` (which wins over the env var),
+// constructing its `App` with
+// `new App({ postCliContext: { 'aws:cdk:bundling-stacks': ['**'] } })`
+// (or the specific stack id).
 const BUNDLING_DISABLED_CONTEXT = { 'aws:cdk:bundling-stacks': [] as string[] };
 
 const existing = process.env.CDK_CONTEXT_JSON;