Add parameter path verification and fix scaffold config for dashboard agents

- Add policyengine-parameter-patterns-skill to backend-builder agent
- Add Step 3b: Verify All Parameter Paths in backend-builder
- Add Check 7: Parameter Path Verification to architecture validator
- Add postcss.config.mjs requirement to scaffold agent (required for Tailwind v4)
- Replace random port selection with 4000-4100 range macro in Makefile templates
- Add copy-pasteable Makefile code for both precomputed and custom-modal patterns

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

Author: anth-volk

agents/dashboard/backend-builder.md

@@ -22,6 +22,7 @@ Builds the data layer for a dashboard based on the approved `plan.yaml`.
 - **policyengine-interactive-tools-skill** - Data patterns and API integration
 - **policyengine-us-skill** or **policyengine-uk-skill** - PolicyEngine variables
 - **policyengine-simulation-mechanics-skill** - How simulations work (custom-backend only)
+- **policyengine-parameter-patterns-skill** - Parameter YAML structure, bracket path syntax, and Reform.from_dict() paths (custom-backend only)
 
 ## Backend Selection Priority
 
@@ -41,6 +42,7 @@ Pattern C is the most complex and should be the last resort. If the plan specifi
 2. `Skill: policyengine-us-skill` (if US dashboard)
 3. `Skill: policyengine-uk-skill` (if UK dashboard)
 4. `Skill: policyengine-simulation-mechanics-skill` (if custom-backend pattern)
+5. `Skill: policyengine-parameter-patterns-skill` (if custom-backend pattern — **required** for correct Reform.from_dict() paths)
 
 ## Input
 
@@ -257,6 +259,39 @@ def run_statewide(params: dict) -> dict:
     return {"revenue_change": ..., "winners": ..., "losers": ...}
 ```
 
+### Step 3b: Verify All Parameter Paths
+
+**CRITICAL — every parameter path used in `Reform.from_dict()` or reform dictionaries MUST be verified against the actual YAML files.** Incorrect paths cause silent failures or runtime errors like "Could not find the parameter". Consult the `policyengine-parameter-patterns-skill` section 6.5 for the bracket path syntax rules.
+
+**Common mistakes:**
+- **Off-by-one indexing**: Some parameters use 1-indexed keys (e.g., `gov.irs.income.bracket.rates` has keys `1`-`7`, not `0`-`6`). Always check whether the YAML uses a list (0-indexed) or explicit integer keys (use those exact keys).
+- **Missing sub-keys on bracket scales**: Bracket/scale parameters (YAML `brackets:` list) require `.amount` or `.rate` after the index. E.g., `gov.irs.credits.eitc.max[0].amount`, NOT `gov.irs.credits.eitc.max[0]`.
+- **Filing-status-indexed parameters**: Some parameters have sub-keys by filing status (e.g., `gov.irs.credits.ctc.phase_out.threshold[SINGLE]`).
+
+**Verification procedure for every parameter path:**
+
+1. Find the YAML file in the `policyengine-us` (or `policyengine-uk`) parameters directory:
+   ```bash
+   # Convert dotted path to directory path and search
+   find $(python3 -c "import policyengine_us; import os; print(os.path.dirname(policyengine_us.__file__))") \
+     -path "*/parameters/gov/irs/income/bracket.yaml" 2>/dev/null
+   ```
+
+2. Read the YAML and check whether the parameter uses:
+   - **Explicit integer keys** (e.g., `1:`, `2:`, `3:`) → use those exact indices: `path[1]`, `path[2]`
+   - **A `brackets:` list** → use 0-indexed with sub-key: `path[0].amount`, `path[0].rate`
+   - **Filing-status sub-keys** → append `[SINGLE]`, `[JOINT]`, etc.
+
+3. Verify programmatically (if policyengine is installed locally):
+   ```python
+   from policyengine_us import CountryTaxBenefitSystem
+   p = CountryTaxBenefitSystem().parameters
+   # Navigate and confirm the path resolves:
+   print(p.gov.irs.income.bracket.rates[1]("2026-01-01"))  # Should return 0.10
+   ```
+
+**Do NOT guess parameter paths from memory.** Always verify against the actual YAML files.
+
 ### Step 4: Create Worker App
 
 Generate `backend/app.py`. Only `modal` at module level. Imports business logic **inside each function body**:

agents/dashboard/dashboard-architecture-validator.md

@@ -12,10 +12,12 @@ Checks that the dashboard uses the correct framework, styling infrastructure, an
 ## Skills Used
 
 - **policyengine-frontend-builder-spec-skill** — Authoritative spec to validate against
+- **policyengine-parameter-patterns-skill** — Bracket path syntax for parameter path verification (custom-modal only)
 
 ## First: Load Required Skills
 
 1. `Skill: policyengine-frontend-builder-spec-skill`
+2. `Skill: policyengine-parameter-patterns-skill` (if `data_pattern: custom-modal`)
 
 After loading the skill, extract every MUST / MUST NOT statement and validate each one.
 
@@ -33,15 +35,21 @@ grep -n '@policyengine/ui-kit/theme.css' app/globals.css
 
 # tailwindcss in package.json
 grep '"tailwindcss"' package.json
+
+# postcss.config.mjs exists with @tailwindcss/postcss
+test -f postcss.config.mjs && grep '@tailwindcss/postcss' postcss.config.mjs
+
+# @tailwindcss/postcss in package.json devDependencies
+grep '@tailwindcss/postcss' package.json
 ```
 
 **Prohibited:**
 ```bash
 # No tailwind.config.ts/js
 test ! -f tailwind.config.ts && test ! -f tailwind.config.js
 
-# No postcss.config
-test ! -f postcss.config.js && test ! -f postcss.config.mjs
+# No old-style postcss.config.js (must be .mjs with @tailwindcss/postcss)
+test ! -f postcss.config.js
 
 # No @tailwind directives
 grep -rn '@tailwind' app/ --include='*.css'
@@ -157,13 +165,67 @@ grep -n 'policyengine' backend/modal_app.py
 # Should find NOTHING — gateway is lightweight
 ```
 
+### 7. Parameter Path Verification (custom-modal only)
+
+**Only run this check if `plan.yaml` has `data_pattern: custom-modal`.** Skip entirely for other patterns.
+
+This validates that all parameter paths used in `Reform.from_dict()` or reform dictionaries in `backend/simulation.py` resolve to real parameters in the policyengine parameter tree.
+
+**Load required skill first:** `Skill: policyengine-parameter-patterns-skill` — see section 6.5 for bracket path syntax rules.
+
+**Step 1: Extract all parameter paths from simulation.py:**
+```bash
+# Find all string literals that look like parameter paths (gov.xxx.yyy)
+grep -oP '"gov\.[a-z_.]+(\[[A-Z_0-9]+\])*(\.[a-z_]+)*"' backend/simulation.py | sort -u
+# Also check for f-string patterns building paths
+grep -n 'gov\.' backend/simulation.py | grep -v '#'
+```
+
+**Step 2: For each parameter path, find and verify the YAML source:**
+```bash
+# Convert a dotted path like gov.irs.income.bracket.rates to a file search
+# The YAML file is at parameters/gov/irs/income/bracket.yaml with rates as a child node
+```
+
+**Step 3: Check indexing correctness:**
+- If the YAML has explicit integer keys (`1:`, `2:`, `3:`, ...): verify the code uses those exact indices, NOT 0-based
+- If the YAML has a `brackets:` list: verify the code uses 0-based indices WITH `.amount` or `.rate` sub-key
+- If the YAML has filing-status sub-keys: verify the code appends `[SINGLE]`, `[JOINT]`, etc.
+
+**Step 4: Verify programmatically (preferred):**
+```bash
+# If policyengine-us is installed locally (e.g., in backend/):
+cd backend && uv run python3 -c "
+from policyengine_us import CountryTaxBenefitSystem
+p = CountryTaxBenefitSystem().parameters
+# Test each path — will raise ParameterNotFoundError if wrong
+paths_to_check = [
+    # Paste extracted paths here
+]
+for path in paths_to_check:
+    try:
+        node = p
+        # Navigate the path
+        # ... (manual or eval-based traversal)
+        print(f'PASS: {path}')
+    except Exception as e:
+        print(f'FAIL: {path} — {e}')
+"
+```
+
+**Common failures to flag:**
+- `rates[0]` when the YAML uses 1-indexed keys (`1:` through `7:`) → FAIL
+- `eitc.max[0]` without `.amount` suffix on a bracket scale → FAIL
+- `rates[0]` without `.rate` suffix on a bracket scale → FAIL
+- Filing-status paths missing the `[SINGLE]`/`[JOINT]` index → FAIL
+
 ## Report Format
 
 ```
 ## Architecture Compliance Report
 
 ### Summary
-- PASS: X/6 checks (or X/5 if not custom-modal)
+- PASS: X/7 checks (or X/5 if not custom-modal)
 - FAIL: Y checks
 
 ### Results
@@ -176,6 +238,7 @@ grep -n 'policyengine' backend/modal_app.py
 | 4 | Package manager | PASS/FAIL | ... |
 | 5 | Tailwind classes used | PASS/FAIL | ... |
 | 6 | Modal backend structure | PASS/FAIL/SKIP | ... |
+| 7 | Parameter path verification | PASS/FAIL/SKIP | ... |
 
 ### Failures (if any)
 

agents/dashboard/dashboard-scaffold.md

@@ -151,7 +151,7 @@ Generate a CLAUDE.md following the pattern from existing applets (givecalc, ctc-
 
 ```bash
 bun install
-make dev            # Full dev stack (Modal + frontend, random port)
+make dev            # Full dev stack (Modal + frontend, port 4000-4100)
 make dev-frontend   # Frontend only
 ```
 
@@ -182,6 +182,8 @@ make build
 Generate from the fixed tech stack, including:
 - `next`, `react`, `react-dom` (^19)
 - `tailwindcss` (^4)
+- `@tailwindcss/postcss` (dev)
+- `postcss` (dev)
 - `@policyengine/ui-kit`
 - `recharts` (if custom charts beyond ui-kit)
 - `react-plotly.js` (if maps in plan)
@@ -201,6 +203,18 @@ const nextConfig: NextConfig = {
 export default nextConfig
 ```
 
+#### postcss.config.mjs
+
+**Required for Tailwind v4.** Without this file, `@import "tailwindcss"` in globals.css is never processed and no utility classes are generated.
+
+```js
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+```
+
 #### app/globals.css
 
 Generate the Tailwind v4 configuration with the ui-kit theme import:
@@ -393,10 +407,21 @@ Generate a `Makefile` that provides standard development targets. The Makefile c
 
 **IMPORTANT:** Makefile recipes must use literal tab characters for indentation, not spaces.
 
-**For all patterns:** The `dev` and `dev-frontend` targets must use a random available port, never hardcode port 3000. Use this Python one-liner to find a free port:
+**For all patterns:** The `dev` and `dev-frontend` targets must try port 4000 first, then increment by 1 up to 4100, erroring out if no port in that range is available. Use this helper script embedded in the Makefile — copy it exactly:
 
-```
-python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()'
+```makefile
+# Port selection helper — finds the first available port in 4000-4100
+define find_port
+$$(python3 -c '\
+import socket, sys;\
+for p in range(4000, 4101):\
+    try:\
+        s = socket.socket(); s.bind(("", p)); s.close(); print(p); sys.exit(0)\
+    except OSError:\
+        continue\
+print("ERROR: no free port in 4000-4100", file=sys.stderr); sys.exit(1)\
+')
+endef
 ```
 
 **For `precomputed`, `policyengine-api`, or `precomputed-csv` patterns:**
@@ -405,26 +430,39 @@ python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsocknam
 .PHONY: dev dev-frontend
 .PHONY: build test lint clean
 
-# Start development server on a random available port
+# Port selection helper — finds the first available port in 4000-4100
+define find_port
+$$(python3 -c '\
+import socket, sys;\
+for p in range(4000, 4101):\
+    try:\
+        s = socket.socket(); s.bind(("", p)); s.close(); print(p); sys.exit(0)\
+    except OSError:\
+        continue\
+print("ERROR: no free port in 4000-4100", file=sys.stderr); sys.exit(1)\
+')
+endef
+
+# Start development server
 dev: dev-frontend
 
 # Frontend only (no backend for this data pattern)
 dev-frontend:
-    @PORT=$$(python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()'); \
-    echo "Starting dev server on http://localhost:$$PORT"; \
-    PORT=$$PORT bun run dev
+	@PORT=$(find_port); \
+	echo "Frontend: http://localhost:$$PORT"; \
+	PORT=$$PORT bun run dev
 
 build:
-    bun run build
+	bun run build
 
 test:
-    bunx vitest run
+	bunx vitest run
 
 lint:
-    bun run lint
+	bun run lint
 
 clean:
-    rm -rf .next node_modules
+	rm -rf .next node_modules
 ```
 
 **For `custom-modal` pattern:**
@@ -437,48 +475,61 @@ The custom-modal pattern uses a **gateway + worker architecture** with frontend
 .PHONY: dev dev-frontend dev-backend deploy-worker
 .PHONY: build test test-backend lint clean
 
+# Port selection helper — finds the first available port in 4000-4100
+define find_port
+$$(python3 -c '\
+import socket, sys;\
+for p in range(4000, 4101):\
+    try:\
+        s = socket.socket(); s.bind(("", p)); s.close(); print(p); sys.exit(0)\
+    except OSError:\
+        continue\
+print("ERROR: no free port in 4000-4100", file=sys.stderr); sys.exit(1)\
+')
+endef
+
 # Deploy worker functions, then start gateway + frontend
 dev:
-    @echo "Deploying worker functions..."
-    @unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET && modal deploy backend/app.py
-    @echo "Starting gateway (ephemeral)..."
-    @modal serve backend/modal_app.py & MODAL_PID=$$!; \
-    sleep 5; \
-    MODAL_URL="https://policyengine--DASHBOARD_NAME-fastapi-app-dev.modal.run"; \
-    PORT=$$(python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()'); \
-    echo "Gateway: $$MODAL_URL"; \
-    echo "Frontend: http://localhost:$$PORT"; \
-    NEXT_PUBLIC_API_URL=$$MODAL_URL PORT=$$PORT bun run dev; \
-    kill $$MODAL_PID 2>/dev/null
+	@echo "Deploying worker functions..."
+	@unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET && modal deploy backend/app.py
+	@echo "Starting gateway (ephemeral)..."
+	@modal serve backend/modal_app.py & MODAL_PID=$$!; \
+	sleep 5; \
+	MODAL_URL="https://policyengine--DASHBOARD_NAME-fastapi-app-dev.modal.run"; \
+	PORT=$(find_port); \
+	echo "Gateway: $$MODAL_URL"; \
+	echo "Frontend: http://localhost:$$PORT"; \
+	NEXT_PUBLIC_API_URL=$$MODAL_URL PORT=$$PORT bun run dev; \
+	kill $$MODAL_PID 2>/dev/null
 
 # Frontend only (uses production API or NEXT_PUBLIC_API_URL if set)
 dev-frontend:
-    @PORT=$$(python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()'); \
-    echo "Starting dev server on http://localhost:$$PORT"; \
-    PORT=$$PORT bun run dev
+	@PORT=$(find_port); \
+	echo "Frontend: http://localhost:$$PORT"; \
+	PORT=$$PORT bun run dev
 
 # Backend only (gateway in dev mode — worker must already be deployed)
 dev-backend:
-    modal serve backend/modal_app.py
+	modal serve backend/modal_app.py
 
 # Deploy worker functions to Modal (required before gateway can spawn jobs)
 deploy-worker:
-    unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET && modal deploy backend/app.py
+	unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET && modal deploy backend/app.py
 
 build:
-    bun run build
+	bun run build
 
 test:
-    bunx vitest run
+	bunx vitest run
 
 test-backend:
-    cd backend && uv run pytest
+	cd backend && uv run pytest
 
 lint:
-    bun run lint
+	bun run lint
 
 clean:
-    rm -rf .next node_modules
+	rm -rf .next node_modules
 ```
 
 #### Favicon
@@ -567,7 +618,8 @@ If either fails, fix before proceeding.
 - [ ] `CLAUDE.md` follows existing applet patterns
 - [ ] `package.json` has all required dependencies (Next.js, Tailwind v4, ui-kit)
 - [ ] `globals.css` has `@import "tailwindcss"` + `@import "@policyengine/ui-kit/theme.css"`
-- [ ] No `tailwind.config.ts` or `postcss.config.js` (Tailwind v4)
+- [ ] `postcss.config.mjs` exists with `@tailwindcss/postcss` plugin
+- [ ] No `tailwind.config.ts` (Tailwind v4)
 - [ ] No CDN `<link>` for design-system tokens (ui-kit theme provides everything)
 - [ ] Inter font is loaded via `next/font/google`
 - [ ] Embedding boilerplate is in place
@@ -580,7 +632,7 @@ If either fails, fix before proceeding.
 - [ ] `layout.tsx` metadata includes `icons: { icon: '/favicon.svg' }`
 - [ ] Header uses `logos.whiteWordmark` or `logos.tealWordmark` (not text-only)
 - [ ] `Makefile` has correct targets for the data pattern
-- [ ] `make dev` uses a random port (does not hardcode 3000)
+- [ ] `make dev` uses port range 4000-4100 (not random, not hardcoded 3000)
 - [ ] If custom-modal: `make dev` deploys worker, then starts gateway + frontend
 - [ ] If custom-modal: backend has 3-file structure (`_image_setup.py`, `app.py`, `simulation.py`)
 - [ ] If custom-modal: `_image_setup.py` has no package imports at module level
@@ -603,7 +655,8 @@ If either fails, fix before proceeding.
 - Deploy to Vercel or Modal (that's `/deploy-dashboard`)
 - Implement real logic (that's Phase 3 agents)
 - Skip the feature branch
-- Create `tailwind.config.ts` or `postcss.config.js` (Tailwind v4 uses `@theme` in CSS)
+- Create `tailwind.config.ts` (Tailwind v4 uses `@theme` in CSS)
+- Omit `postcss.config.mjs` — it IS required for Tailwind v4 (the `@tailwindcss/postcss` plugin processes `@import "tailwindcss"`)
 - Rebuild components that exist in `@policyengine/ui-kit`
 - Load tokens via CDN `<link>` (use `@import "@policyengine/ui-kit/theme.css"` instead)
 - Use `getCssVar()` — it no longer exists. SVG accepts `var()` directly.