# v2.14.x Deferrals Cleanup 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:** Close the remaining small-hygiene deferrals from the v2.14.x cycle inside the v2.15.0 release, alongside the sprint-skills work, so v2.14.x is fully retired and the v2.16+ backlog carries only larger structural items.

**Architecture:** No new architecture. This plan touches CI workflow files (Node version pins) and one internal-docs file (AGENTS/claude/CONTEXT.md per-phase tables). No public-API or skill-catalog changes.

**Tech Stack:** GitHub Actions YAML workflows; internal docs markdown.

**Cross-references:**
- Parent release: pm-skills v2.15.0 (sprint-skills release; see `foundation-sprint-integration-plan.md` and `design-sprint-integration-plan.md`)
- Source of truth for v2.14.x deferrals: `AGENTS/SESSION-LOG/2026-05-10_07-00_claude_v2.14.0-tag-ship-and-post-tag-followups.md` section "Updated v2.15+ deferral list (post-v2.14.2)"
- Items deferred to v2.16+ (out of scope here): see `docs/internal/release-plans/v2.16.0/plan_v2.16.0.md`

---

## Status

Draft. Created 2026-05-11 alongside the sprint-skills integration plans.

## Original Tier 1 Deferral List Status Audit

Six items were originally identified as "v2.14.x deferrals to bundle into v2.15.0". After git-log audit on 2026-05-11, four are already closed by v2.14.1 follow-up commits. Only two remain actionable.

| # | Item | Status | Closing commit / Open task |
|---|---|---|---|
| 1 | bash/pwsh parity: 7 broken links in foundation-meeting SKILL.md files | CLOSED | `b797a0d` FU6 in v2.14.1 (generator path-rewrite + EXAMPLE.md backtick fix + LC_ALL=C.UTF-8 locale fallback; `check-internal-link-validity` promoted to truly enforcing) |
| 2 | Node 20 to 22 upgrade for remaining workflows | OPEN | Task 1 below (3 workflows still on Node 20; 2 already on Node 22) |
| 3 | docs/changelog.md backfill for v2.13.x | CLOSED | `0bcbf33` FU3 in v2.14.1 (v2.13.0 + v2.13.1 entries restored) |
| 4 | README stubs for docs/ subdirectories | CLOSED | `2dd81b0` FU7 in v2.14.1 (7 README stubs across docs/{skills,guides,concepts,contributing,getting-started,showcase,releases}/) |
| 5 | Working-tree gitignore decision for 3 session artifacts | CLOSED | `7ca3c31` FU2 in v2.14.1 (.playwright-mcp/ + w11-home-*.png gitignored) |
| 6 | AGENTS/claude/CONTEXT.md Skills Inventory per-phase tables refresh | OPEN | Task 2 below (stale at v2.10.x-era 32-skill catalog; actual is 40) |

The audit findings are recorded so future readers can see the cleanup landscape at v2.15.0 cycle-start without re-tracing git log.

## Scope

This plan covers three tasks:

1. Bump 3 lagging GitHub Actions workflows from Node 20 to Node 22 (matches the already-upgraded `deploy-pages.yml` and `validation.yml`)
2. Refresh AGENTS/claude/CONTEXT.md per-phase tables from the v2.10.x-era 32-skill catalog to the current v2.15.0 catalog (26 phase + 8 foundation + 6 utility + 15 tool = 55)
3. Close 14 of 17 open Dependabot alerts via Astro 5.x bump + Mermaid override (3 remaining alerts require Astro 6.x and stay deferred to v2.16)

Out of scope:

- Astro 6 + Node 22.12+ upgrade (Tier 2; deferred to v2.16; would unify Node versions on Node 22.12+ at that time AND clear the 3 remaining Dependabot alerts)
- All other Tier 2 items (tags-as-feature, URL slug normalization, sync-agents-md.yml full rewrite)

## Prerequisites

- pm-skills v2.14.2 stable on origin/main
- v2.15.0 release cycle has begun (sprint-skills authoring underway or complete; CONTEXT.md refresh in Task 2 should land near the end of the cycle so it reflects the post-sprint catalog)

## File Structure

### Files to modify (4 files)

**Node version pins (3 files)**
- `.github/workflows/create-issues-from-drafts.yml`: `node-version: '20'` to `'22'`
- `.github/workflows/validate-mcp-sync.yml`: `node-version: 20` to `22`
- `.github/workflows/validate-plugin.yml`: `node-version: 20` to `22`

**Skills inventory refresh (1 file)**
- `AGENTS/claude/CONTEXT.md`: regenerate per-phase tables in the "Skills Inventory" section against the current 40-skill catalog

### Files NOT modified

- `.github/workflows/deploy-pages.yml`: already on Node 22
- `.github/workflows/validation.yml`: already on Node 22

---

## Tasks

### Phase 1: Node version unification

#### Task 1: Bump 3 lagging workflows to Node 22

**Files:**
- Modify: `.github/workflows/create-issues-from-drafts.yml`
- Modify: `.github/workflows/validate-mcp-sync.yml`
- Modify: `.github/workflows/validate-plugin.yml`

**Rationale:** Two workflows (`deploy-pages.yml`, `validation.yml`) were bumped to Node 22 during v2.14 Phase 3 (Astro Starlight migration). The other three workflows were not touched because they don't run Astro builds. Bumping them to Node 22 unifies the Node version across all five workflows, removes a CI maintenance asymmetry, and stays inside the no-Astro-6 scope. The next bump (Node 22.12+ for Astro 6) is deferred to v2.16.

- [ ] **Step 1: Read each workflow's current Node version**

```bash
grep -n "node-version" .github/workflows/create-issues-from-drafts.yml
grep -n "node-version" .github/workflows/validate-mcp-sync.yml
grep -n "node-version" .github/workflows/validate-plugin.yml
```

Expected: line 28 (create-issues), line 46 (validate-mcp-sync), line 41 (validate-plugin).

- [ ] **Step 2: Update each file**

Change `node-version: '20'` to `node-version: '22'` (or `node-version: 20` to `node-version: 22` if quotes are absent). Preserve the existing quoting style per file to avoid spurious diffs.

- [ ] **Step 3: Validate YAML still parses**

```bash
node -e "require('js-yaml').load(require('fs').readFileSync('.github/workflows/create-issues-from-drafts.yml','utf-8'))"
node -e "require('js-yaml').load(require('fs').readFileSync('.github/workflows/validate-mcp-sync.yml','utf-8'))"
node -e "require('js-yaml').load(require('fs').readFileSync('.github/workflows/validate-plugin.yml','utf-8'))"
```

Expected: no errors.

- [ ] **Step 4: Push and verify CI**

Push the change to a feature branch or directly to main per current branch policy. Verify that each workflow runs and passes on Node 22. Watch for: (a) any `npm ci` step failure caused by an `engines.node` mismatch; (b) any package that warned about Node 20 deprecation on the prior run.

- [ ] **Step 5: Commit**

```bash
git add .github/workflows/create-issues-from-drafts.yml .github/workflows/validate-mcp-sync.yml .github/workflows/validate-plugin.yml
git commit -m "ci(v2.15): bump 3 lagging workflows from Node 20 to Node 22"
```

### Phase 2: CONTEXT.md skills inventory refresh

#### Task 2: Refresh per-phase tables to 40-skill catalog

**Files:**
- Modify: `AGENTS/claude/CONTEXT.md` (Skills Inventory section, currently flagged stale at line 526)

**Rationale:** Per the v2.14.2 close-out deferral list, the per-phase tables in CONTEXT.md are still at the v2.10.x-era 32-skill catalog (26 phase + 1 foundation + 5 utility). The authoritative current catalog (40 skills: 26 phase + 8 foundation + 6 utility) has been live since v2.12.0 but the AGENTS-facing context file lagged. Refreshing this table improves first-session orientation for any agent reading CONTEXT.md.

**Sequencing note:** Do this task AFTER all sprint-skills authoring is complete (Task 21 of the foundation-sprint plan and the final task of the design-sprint plan). Otherwise the refresh will need a second pass when sprint skills land.

- [ ] **Step 1: Inventory the current skills catalog**

```bash
ls skills/ | sort
```

Confirm: 26 phase skills (prefixed `discover-`, `define-`, `develop-`, `deliver-`, `measure-`, `iterate-`), 8 foundation skills (prefixed `foundation-`), 6 utility skills (prefixed `utility-`), plus 15 tool skills shipped earlier in v2.15.0 (all prefixed `tool-`: `tool-foundation-sprint-*` x7, `tool-design-sprint-*` x7, `tool-note-and-vote`).

- [ ] **Step 2: Confirm authoritative cross-references**

Read `docs/reference/categories.md` (taxonomy + counts) and `docs/skills/index.md` (curated index). These are the authoritative sources per the CONTEXT.md stale-table note. If they are also stale, fix them first or include the fix in this task.

- [ ] **Step 3: Author the refreshed per-phase tables**

Replace the stale section starting at line 526 (`> **Note (refresh deferred to v2.14.0+)**`) and the "Foundation (1 skill, stale - actual is 8)" header below it with the current 55-skill catalog (post-v2.15.0). Use the same table format as the existing per-phase tables, but with accurate counts and skill names. Add a row for the new `tool` classification (15 skills: 7 `tool-foundation-sprint-*` + 7 `tool-design-sprint-*` + 1 `tool-note-and-vote`).

- [ ] **Step 4: Remove the stale-table warning**

Once the refresh is in place, delete the "Note (refresh deferred to v2.14.0+)" block. The presence of that warning is itself a defect once the tables are accurate.

- [ ] **Step 5: Update the top-of-file Status block**

The Status block on line 5 still reads "v2.14.0 SHIPPED". When this task runs, also refresh that block to reflect the current v2.15.0 release state (HEAD, ship date, what changed).

- [ ] **Step 6: Commit**

```bash
git add AGENTS/claude/CONTEXT.md
git commit -m "docs(v2.15): refresh CONTEXT.md per-phase tables to 55-skill catalog (closes v2.14.x deferral)"
```

### Phase 3: Dependabot triage and patch

#### Task 3: Clear 14 of 17 Dependabot alerts via Astro 5.x bump + Mermaid override

**Files:**
- Modify: `package.json` (bump `astro` from `~5.13.0` to `^5.18.1`; add `overrides.mermaid: ^11.15.0`)
- Regenerate: `package-lock.json` (via `npm install`)

**Triage outcome (recorded 2026-05-15):**

| Severity | Count | Packages and alert numbers | Disposition |
|---|---|---|---|
| High | 2 | astro #5 (reflected XSS server islands; patch 5.15.8), devalue #17 (DoS via sparse array; patch 5.8.1; transitive of astro) | CLOSE in v2.15.0 via Astro 5.18.1 bump |
| Medium | 6 | astro #1, #3, #6, #7, #8 (patches 5.14.3 through 5.15.9); astro #10 (patch 6.1.6) | 5 CLOSE via Astro 5.18.1 bump; #10 DEFER to v2.16 (Astro 6.x required) |
| Medium | 4 | mermaid #11, #12, #13, #14 (patch 11.15.0) | CLOSE via `overrides.mermaid: ^11.15.0` in package.json |
| Low | 5 | astro #2, #4, #9 (patches 5.14.3 through 5.18.1); astro #15, #16 (patch 6.1.10) | 3 CLOSE via Astro 5.18.1 bump; #15, #16 DEFER to v2.16 |

Net: 14 of 17 close in v2.15.0; 3 remain for v2.16 (already documented in `docs/internal/release-plans/v2.16.0/plan_v2.16.0.md` Astro 6 + Node 22.12+ row).

**Rationale:** Astro 5.18.1 is the current 5.x line tip and exactly matches Dependabot's `first_patched_version` for the high-severity reflected-XSS alert plus 8 other in-line patches. Same-major bump (5.13.0 to 5.18.1) is a low-risk patch path that stays inside the no-Astro-6 scope. Mermaid is a transitive of astro-mermaid 2.0.1 (latest); astro-mermaid 2.0.x has not shipped a Mermaid 11.15.0 bump, so an `overrides` entry is the standard pattern to force the transitive forward without waiting for upstream.

- [ ] **Step 1: Bump Astro in package.json**

Change `"astro": "~5.13.0"` to `"astro": "^5.18.1"`. Caret range (^) allows future 5.x patches and minors but not 6.x; that's deliberate since 6.x is the v2.16 deferral.

- [ ] **Step 2: Add Mermaid override in package.json**

Add this top-level field to package.json:

```json
"overrides": {
  "mermaid": "^11.15.0"
}
```

If `overrides` already exists, merge the entry in. The caret range matches Mermaid's current 11.x line.

- [ ] **Step 3: Regenerate package-lock and verify resolution**

```bash
rm -rf node_modules
npm install
npm ls astro mermaid devalue
```

Expected: `astro@5.18.1`, `mermaid@^11.15.0`, `devalue@^5.8.1` (the devalue bump is transitive via astro).

- [ ] **Step 4: Build verification**

```bash
npm run build
```

Expected: Astro build succeeds; Mermaid renders in any concept docs that include diagrams; no Starlight 0.34.x compat regressions. If the build fails on Starlight side, bump `@astrojs/starlight` to current `~0.34.x` tip or open a separate spike to evaluate Starlight 0.35.x.

- [ ] **Step 5: Re-fetch Dependabot alert state**

```bash
gh api 'repos/product-on-purpose/pm-skills/dependabot/alerts?state=open' --jq '. | length'
```

Expected: 3 (the deferred Astro 6.x alerts #10, #15, #16). If higher, investigate which transitive did not pull forward and adjust overrides.

- [ ] **Step 6: Commit**

```bash
git add package.json package-lock.json
git commit -m "deps(v2.15): bump astro to 5.18.1 + mermaid override 11.15.0 (closes 14 of 17 dependabot alerts)"
```

- [ ] **Step 7: Update plan_v2.16.0.md to reflect the 3 remaining alerts**

Add a row to the Astro 6 + Node 22.12+ entry noting that the upgrade also closes Dependabot alerts #10, #15, #16 (define:vars XSS + server-island encrypted-parameter replay).

---

## Effort Estimate

| Task | Estimated effort |
|---|---|
| Task 1: Node 22 bump on 3 workflows | 15 to 30 minutes (most of it is waiting on CI verification) |
| Task 2: CONTEXT.md skills inventory refresh | 1 to 1.5 hours (table authoring + Status block refresh + verification against `docs/reference/categories.md`) |
| Task 3: Dependabot triage and patch | 30 to 60 minutes (package.json edit is small; npm install + build verification is the bulk) |
| **Total** | **~2 to 3.5 hours; one focused session, or folded into pre-tag cleanup pass** |

## Sequencing in v2.15.0

- **Task 1 (Node bump):** can run any time during v2.15.0; no dependency on sprint-skills authoring.
- **Task 2 (CONTEXT.md refresh):** MUST run after sprint-skills authoring is complete so the refresh reflects the final v2.15.0 catalog.

Suggested order: Task 1 anywhere in the cycle, Task 2 in the final pre-tag pass.

## Self-Review Notes

- The original Tier 1 list (6 items) is preserved in the status audit table above so future readers see both what was completed in v2.14.1 (4 items) and what carried forward (2 items). Without that audit, the v2.14.x deferral story would be hard to reconstruct.
- The Node target is Node 22, not Node 24. Rationale: matches the already-deployed Node 22 on `deploy-pages.yml` and `validation.yml`; the Astro 6 + Node 22.12+ upgrade in v2.16 will be the next Node bump, but skipping straight to Node 24 now would mean an out-of-order downgrade then.
- This plan does NOT touch `package.json` `engines.node`. That field, if present, should already permit Node 22; if it pins to Node 20 specifically, that is a separate task and should be raised in v2.16 alongside the Astro 6 upgrade.
- The CONTEXT.md refresh in Task 2 is deliberately scoped narrowly: just the per-phase tables and the Status block. Broader CONTEXT.md drift (other stale references) is out of scope for this task and would warrant its own refresh task.
