Monthly Dependency Updates (July 2026) Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Bring the project's npm deps current for July 2026 — patches, minors, the safe postcss-preset-env v11 major, and npm audit fix — without breaking the build or the site's appearance. Defer tailwindcss v4 to a dedicated session.

Architecture: Risk-tiered phases executed in order on a single branch: patch batch → minor batch → each major individually → audit fix → final visual check & merge. Each phase is one commit. Build must pass after every phase; visual checks (human) gate the majors and the final merge.

Tech Stack: 11ty 3.x, Alpine.js 3.x, Tailwind CSS 3.4.x (PostCSS-based), Node.js, npm. Build = npm run build (eleventy + npx tailwindcss). Dev = npm run dev (eleventy --serve + tailwind watch).

Global Constraints

Branch: stay on docs/add-dependency-update-runbook this month (runbook rides along in same PR). Future months use chore/dep-updates-YYYY-MM per the runbook.
Commit style: conventional commits, one per phase:
- Phase 1: chore(deps): bump patch versions 2026-07
- Phase 2: chore(deps): bump minor versions 2026-07
- Phase 3 (per major): chore(deps)!: bump <pkg> to v<N>
- Phase 4: chore(security): npm audit fix 2026-07
Build gate: npm run build must exit 0 after every phase. No exceptions.
Visual gate: npm run dev + human browser check across the runbook's Visual check pages for majors and final merge.
No --force, no lockfile hand-edits. Deferred majors use git checkout package.json package-lock.json && npm ci.
tailwindcss v4 is deferred this month. Stay on 3.4.19 (patch). Note deferral + reason in the PR.

Baseline (recorded 2026-07-27)

npm outdated:

Dep	Current	Wanted	Latest	Tier this month
@11ty/eleventy	3.1.2	3.1.6	3.1.6	Patch
@11ty/eleventy-upgrade-help	3.0.1	3.0.2	3.0.2	Patch
alpinejs	3.15.0	3.15.12	3.15.12	Patch
postcss	8.5.6	8.5.23	8.5.23	Patch
tailwindcss	3.4.17	3.4.19	4.3.3	Patch (v4 deferred)
autoprefixer	10.4.21	10.5.4	10.5.4	Minor
postcss-preset-env	10.4.0	10.6.1	11.3.2	Minor → Major

npm audit --omit=dev: 11 vulnerabilities (1 critical, 8 high, 2 moderate). All report "fix available via npm audit fix". Includes postcss <=8.5.17 — likely resolved organically by the postcss 8.5.23 patch bump in Phase 1.

Task 1: Phase 1 — Patches

Files:

Modify: package.json, package-lock.json

Goal: Bump all patch-tier deps to their Wanted versions in one batch, verify build, commit.

[ ] Step 1: Confirm clean tree and baseline

Run:

git status --short

Expected: empty output (clean tree on docs/add-dependency-update-runbook).

[ ] Step 2: Install all patch-tier deps at their Wanted versions

Run:

npm install @11ty/eleventy@3.1.6 @11ty/eleventy-upgrade-help@3.0.2 alpinejs@3.15.12 postcss@8.5.23 tailwindcss@3.4.19

Expected: npm reports "added/changed X packages", exit 0, no peer-dep errors.

[ ] Step 3: Verify the bumps landed in package.json

Run:

npm outdated

Expected: the five deps above no longer appear (or appear only with a higher Latest for majors). tailwindcss should show Current 3.4.19, Wanted 3.4.19, Latest 4.3.3.

[ ] Step 4: Build must pass

Run:

npm run build

Expected: exits 0, _site/ regenerated, no errors from eleventy or tailwindcss.

[ ] Step 5: Quick audit check (informational)

Run:

npm audit --omit=dev

Expected: the postcss <=8.5.17 advisory should be gone (we're now on 8.5.23). Remaining advisories are still expected — they'll be handled in Phase 4. No action here.

[ ] Step 6: Commit

Run:

git add package.json package-lock.json
git commit -m "chore(deps): bump patch versions 2026-07"

Expected: commit created, only package.json + package-lock.json in the diff.

Task 2: Phase 2 — Minors

Files:

Modify: package.json, package-lock.json

Goal: Bump all minor-tier deps to their Wanted versions, verify build, commit.

[ ] Step 1: Install minor-tier deps at their Wanted versions

Run:

npm install autoprefixer@10.5.4 postcss-preset-env@10.6.1

Expected: exit 0, no peer-dep errors.

[ ] Step 2: Verify

Run:

npm outdated

Expected: autoprefixer and postcss-preset-env no longer show a Wanted gap. postcss-preset-env should show Current 10.6.1, Wanted 10.6.1, Latest 11.3.2 (the major remains for Phase 3).

[ ] Step 3: Build must pass

Run:

npm run build

Expected: exits 0.

[ ] Step 4: Commit

Run:

git add package.json package-lock.json
git commit -m "chore(deps): bump minor versions 2026-07"

Expected: commit created.

Task 3: Phase 3a — Major: postcss-preset-env v11.3.2 (attempt)

Files:

Modify: package.json, package-lock.json

Goal: Bump postcss-preset-env to v11 (the Latest). Low risk: postcss.config.js only loads tailwindcss + autoprefixer, and the build uses the tailwind CLI directly, so postcss-preset-env is not in the active pipeline. Visual check confirms.

Defer escape hatch: if build or visual check fails and the fix is not quick, run git checkout package.json package-lock.json && npm ci, note the deferral with reason in the PR, and stop this task at the failed step.

[ ] Step 1: Skim the v11 changelog for breaking changes

Fetch: https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/CHANGELOG.md Look for: stage / preset / option renames, dropped Node versions, removed features. Note anything that looks like it would affect a default-options usage.

[ ] Step 2: Install the major

Run:

npm install postcss-preset-env@latest

Expected: exit 0. If npm reports a peer-dep conflict with postcss 8.5.23, that's a blocker — defer (escape hatch above).

[ ] Step 3: Verify the bump

Run:

npm outdated

Expected: postcss-preset-env no longer appears in npm outdated (Current 11.3.2 = Latest).

[ ] Step 4: Build must pass

Run:

npm run build

Expected: exits 0, no errors.

[ ] Step 5: Visual check — HUMAN GATE

Run:

npm run dev

Then in a browser, visit each of the Visual check pages and confirm layout, Tailwind styling, and Alpine interactions work:

/ — home
/properties/ — listing index
/property-in-victoria/ (or /nadur/, /gharb/, /xaghra/) — a location page
/search/ — search page (Alpine-driven)
/favourites/ — favourites page (Alpine-driven)
/contact-us/
/buying-guide/

What to look for: page renders without errors, Tailwind classes applied (colors, spacing, container width), Alpine-powered interactions work (search filtering, favourites toggle), no broken layouts or missing styles.

If visual check fails → defer: stop the dev server, run git checkout package.json package-lock.json && npm ci, note "postcss-preset-env v11 deferred: visual check failed — " for the PR, and skip the commit step below.

If visual check passes: stop the dev server (Ctrl-C) and proceed to commit.

[ ] Step 6: Commit (only if not deferred)

Run:

git add package.json package-lock.json
git commit -m "chore(deps)!: bump postcss-preset-env to v11"

Expected: commit created.

Task 4: Phase 3b — Major: tailwindcss v4 (DEFERRED)

Files: none this month.

Goal: No action. Record the deferral reason for the PR body.

[ ] Step 1: Confirm deferral

No commands. tailwindcss stays at 3.4.19 (the Phase 1 patch bump). The v4 migration touches postcss.config.js, css/tailwind.css, tailwind.config.js (custom emerald colors, container settings, variants.extend, @tailwindcss/aspect-ratio plugin), and the npm run dev / npm run build scripts (v4 CLI differs). This is realistic to defer to a dedicated session per the runbook's "Known tricky majors" appendix.

[ ] Step 2: Draft PR note

For the PR body, include:

Deferred: tailwindcss v4.3.3 — CSS-first-config major requiring PostCSS plugin swap (@tailwindcss/postcss), rewrite of @tailwind directives to @import "tailwindcss", port of custom theme/container/variants/aspect-ratio plugin to @theme blocks, and build-script changes. Deferred to a dedicated session per the runbook. Currently on 3.4.19 (latest v3 patch).

Task 5: Phase 4 — Security audit

Files:

Modify: package.json, package-lock.json (possibly — npm audit fix may bump transitive deps in the lockfile only)

Goal: Apply safe security fixes via npm audit fix, verify build, commit. Note any remaining unfixable advisories.

[ ] Step 1: See what remains after the version bumps

Run:

npm audit --omit=dev

Expected: fewer advisories than baseline. The postcss advisory should already be gone from Phase 1. Record the remaining count + packages for the PR.

[ ] Step 2: Apply safe fixes

Run:

npm audit fix

Expected: npm reports "fixed X vulnerabilities", exit 0. No --force — if npm says a fix requires --force, skip it and note it as remaining.

[ ] Step 3: Confirm what's left

Run:

npm audit --omit=dev

Expected: either "no vulnerabilities" or a short list of remaining (typically transitive) advisories. Record for PR: advisories fixed by npm audit fix, and any still open with reasons (e.g. "awaiting upstream release", "would require --force").

[ ] Step 4: Build must pass

Run:

npm run build

Expected: exits 0.

[ ] Step 5: Commit (if there were lockfile changes)

Run:

git status --short

If package-lock.json (and/or package.json) changed:

git add package.json package-lock.json
git commit -m "chore(security): npm audit fix 2026-07"

If nothing changed (all advisories already resolved by Phase 1/2/3 bumps): skip the commit, note in PR that npm audit fix was a no-op after the bumps.

Task 6: Phase 5 — Final verification & merge prep

Files: none (verification + PR creation).

Goal: Full visual check, rebase onto latest main, build post-rebase, push, open PR. Merge is a separate human decision.

[ ] Step 1: Visual check — HUMAN GATE

Run:

npm run dev

Then in a browser, visit each of the Visual check pages and confirm layout, Tailwind styling, and Alpine interactions work as expected across all pages.

If anything is broken: stop, identify which phase introduced the regression, git revert <commit> (or git reset --hard <previous-phase-commit>), and re-run the affected phase. Do not merge a broken build.

If all pass: stop the dev server (Ctrl-C).

[ ] Step 2: Rebase onto latest main

Run:

git fetch origin
git rebase origin/main

Expected: clean rebase (CloudCannon may have pushed content meanwhile). If conflicts in docs/ or elsewhere, resolve them, then:

git rebase --continue

[ ] Step 3: Build must pass post-rebase

Run:

npm run build

Expected: exits 0.

[ ] Step 4: Push branch

Run:

git push -u origin docs/add-dependency-update-runbook

(Or git push --force-with-lease if rebasing required a force-push.)

[ ] Step 5: Open PR

Run:

gh pr create --title "chore(deps): monthly dependency updates 2026-07" --body "$(cat <<'EOF'
## Summary

Monthly dependency updates for July 2026, per `docs/dependency-update-runbook.md`.

### Bumps

| Dep | From | To | Tier |
|---|---|---|---|
| @11ty/eleventy | 3.1.2 | 3.1.6 | patch |
| @11ty/eleventy-upgrade-help | 3.0.1 | 3.0.2 | patch |
| alpinejs | 3.15.0 | 3.15.12 | patch |
| postcss | 8.5.6 | 8.5.23 | patch |
| tailwindcss | 3.4.17 | 3.4.19 | patch |
| autoprefixer | 10.4.21 | 10.5.4 | minor |
| postcss-preset-env | 10.4.0 | 11.3.2 | major |

### Advisories fixed by `npm audit fix`
<!-- fill in from Phase 4 Step 3 output -->

### Deferred
- **tailwindcss v4.3.3** — CSS-first-config major requiring PostCSS plugin swap (`@tailwindcss/postcss`), rewrite of `@tailwind` directives to `@import "tailwindcss"`, port of custom theme/container/variants/aspect-ratio plugin to `@theme` blocks, and build-script changes. Deferred to a dedicated session per the runbook. Currently on 3.4.19 (latest v3 patch).

### Advisories still open
<!-- fill in from Phase 4 Step 3 output, or "none" -->

### Verification
- [x] `npm run build` passes after every phase
- [x] Visual check passed across runbook pages (post-rebase)
EOF
)"

Expected: PR URL returned. Paste the audit/deferred details into the PR body where the placeholders are.

[ ] Step 6: Merge — HUMAN DECISION

Review the PR, then merge to main (squash or merge commit per repo convention — check git log --oneline -5 for prior style). This is a human decision, not automated.