misterpropre 0.0.1

package/skills/dependabot-purge/SKILL.md.tmpl

@@ -0,0 +1,137 @@
+---
+name: {{INSTALL_NAME}}
+description: "Triage open dependency-update PRs from Renovate and Dependabot on a single {{ORG}} GitHub repo. Converts drafts to ready, waits for fresh CI, auto-merges only low-risk green patch/minor updates after a changelog/usage breakage analysis, runs every major through a fix engine and hands it off, routes risky updates to a human via NOTIFY events, and fixes failing PRs until CI is green. Use when: purge renovate PRs, merge dependabot PRs, clean up dependency PRs. Invocation: /{{INSTALL_NAME}} <repo-name>"
+user-invocable: true
+---
+
+<!-- {{MANAGED_MARKER}} — generated from misterpropre's bundled template. Edits here are overwritten by `mrp skills install`. -->
+
+# Dependabot Purge (misterpropre)
+
+Triage every open Renovate/Dependabot dependency PR on **one** `{{ORG}}` repo: auto-merge the safe ones, hand the rest to a human via NOTIFY events, and fix failing ones where feasible.
+
+## Runtime contract (read first)
+
+You are invoked **by the misterpropre orchestrator**:
+- Your **current working directory is the repo clone**. Use it for `gh` operations. For fixing failing PRs, create **isolated git worktrees** (see `references/fix-matrix.md`) — **never** `git checkout`/`switch` the clone itself (it may be dirty / on a feature branch).
+- **Notifications are events, not Telegram.** On every needs-human outcome, print a `MISTERPROPRE_NOTIFY_V1` line (format below); the CLI dispatches it to the configured channel. Do NOT call any telegram script.
+- End with exactly one `MISTERPROPRE_RESULT_V1` summary line. The orchestrator reconciles the real outcome from GitHub; your line is a hint.
+
+The skill's bundled scripts/references are alongside this file; call them by absolute path via `$SKILL_DIR` (this skill's directory).
+
+## Golden rules
+
+- **Operate autonomously.** Never ask the user to approve a per-PR decision — the merge-policy table is authoritative; apply it and act.
+- **Never disturb the clone's working tree.** Read-only steps use `gh … --repo`; the fix path uses an isolated worktree.
+- **Auto-merge requires ALL of:** PR was already green (we didn't touch it) AND bump is patch/minor (a `0.x`→`0.y` bump counts as **major**) AND the breakage analysis is clean.
+- **Never auto-merge** a major, a risky bump, or any PR the skill modified — those go to a human.
+- **Every major is analyzed + run through the fix engine, then handed off** (never auto-merged); never punt a major with "go read the release notes".
+- **Never count a draft's stale `skipped` checks as passing.** Wait for fresh post-conversion runs.
+- Comment **only** when NOT merging. Auto-merges are silent.
+- Skip any PR already carrying `purge:needs-human` (idempotent re-runs).
+
+## Step 0: Preconditions
+
+Run in order; stop on first failure.
+1. **npm auth** — `npm whoami`. On `401`/error, **STOP**: private `{{PKG_SCOPE}}/*` packages can't install. Emit `MISTERPROPRE_RESULT_V1 {"v":1,"phase":"purge","kind":"FAIL","message":"npm auth"}` and report.
+2. **npm-only gate** — require a `package.json` in the clone. If none, STOP ("non-npm repo, out of scope"), emit a FAIL result.
+3. **Base branch** — `{{BASE_BRANCH}}` if it exists, else the repo default. `git fetch origin {base}`. Do **not** checkout the clone.
+4. **Classify repo type** — suffix `-back`=backend, `-front`=frontend, `-qa`=qa, else infer from scripts. Selects the matrix in `references/fix-matrix.md`.
+5. **Label** — ensure the label exists: `gh label create purge:needs-human --repo {{ORG}}/{repo} --color B60205 --description "needs human review" 2>/dev/null || true`.
+
+## Step 1: Discover PRs
+
+```bash
+gh pr list --repo {{ORG}}/{repo} --author "app/renovate"   --state open --json number,title,isDraft,headRefName,labels,createdAt
+gh pr list --repo {{ORG}}/{repo} --author "app/dependabot" --state open --json number,title,isDraft,headRefName,labels,createdAt
+```
+Skip any PR labeled `purge:needs-human`. Merge both lists, **sort oldest→newest**, process **sequentially**.
+
+## Step 2: Per-PR pipeline (oldest first)
+
+**A0. Hard skip-gate.** Re-fetch the PR's current `state`+`labels` now (the Step 1 list goes stale within a run):
+- `state` != `OPEN` → **skip** (merged/closed/superseded). Record `skipped-closed`, continue. (Closed PRs have UNKNOWN mergeable forever — any wait loop hangs.)
+- labels include `purge:needs-human` → **skip** entirely. Record `skipped-labeled`, continue. The label is final.
+
+**A. Make ready.** If draft: `gh pr ready {n} --repo {{ORG}}/{repo}` (triggers fresh CI).
+
+**B. Wait for fresh checks.** `bash "$SKILL_DIR/scripts/wait_checks.sh" {{ORG}}/{repo} {n}`:
+- `PASS` → D. `FAIL` → E (fix path).
+- `NO_CHECKS`/`TIMEOUT` → **environmental**, not the PR's fault. Add ONE comment documenting it; do **NOT** label or NOTIFY. Record `no-CI-deferred`; the next run retries.
+
+**C. Determine bump type** from the title/version delta: `patch` | `minor` | `major`. Any `0.x`→`0.y` is **major**.
+
+**D. Checks GREEN:**
+- **patch/minor** → run the **breakage analysis** (Step 3): clean → **auto-merge** (silent): `gh pr review {n} --repo {{ORG}}/{repo} --approve` then `gh pr merge {n} --repo {{ORG}}/{repo} --squash --delete-branch`. risky → comment + label + NOTIFY.
+- **major** → **Major pipeline (Step 3M)**. Never auto-merge.
+
+**E. Checks FAILING / conflicting:**
+- **major** → **Major pipeline (Step 3M)**.
+- **patch/minor** → **fix path** (`references/fix-matrix.md`): isolated worktree, reproduce, fix (mechanical + code adaptation), rebase onto `{base}`, ≤3 push/CI cycles. CI green → NOTIFY "fix ready" + label (no auto-merge). Can't fix → comment + label + NOTIFY "couldn't fix".
+
+**F. After any merge:** `git fetch origin {base}`. Re-verify each remaining PR before deciding; route stale/conflicting ones through E.
+
+## Step 3: Breakage analysis (green patch/minor only)
+
+Merge only if **both** are clean: (1) **Changelog** — WebFetch the package's release notes for the version range; scan for breaking-change language. (2) **Usage grep** — grep the repo for how the API is used. Any doubt → **risky** → hand off.
+
+**Internal `{{PKG_SCOPE}}/*` packages are TRUSTED on patch/minor** (you own them; semver-respecting) — a missing public changelog is NOT a risk signal; let them flow to auto-merge. Internal **majors** still go through the Major pipeline + always hand off.
+
+## Step 3M: Major pipeline (analysis + verify + fix)
+
+Runs for **every major**. Never auto-merged. Reuses the fix engine (`references/fix-matrix.md`).
+1. **Breakage analysis (always)** — WebFetch release notes across the **full** version range; list each breaking change; grep our code for whether it reaches us (npm → imports/APIs/config; GitHub Action → workflow steps; Docker → Dockerfile).
+2. **Worktree + local checks** — isolated worktree, `npm install`, run the matrix.
+3. **Decide:** local + CI green → **verified-good** (comment lists breakages checked + behavioral risks to watch) + label + NOTIFY "verified — review & merge". Red → **fix** (≤3 cycles): reached green → **fixed** (comment per-breakage) + label + NOTIFY; budget exhausted/needs decision → **couldn't-fix** + label + NOTIFY. **Only fix what a check actually catches** — behavioral risks go in the comment, not a speculative edit.
+
+Comment shape (analysis first, never an ask): enumerate each breakage as ✓ no impact / 🔧 fixed / ⚠ watch during review / ⛔ blocking, then a recommendation. A comment that says "go read the release notes" is a bug.
+
+## Merge policy (decision table)
+
+| PR state | Bump | Analysis | Action |
+|---|---|---|---|
+| Green, untouched | patch/minor | clean | **Auto-merge** (approve + squash), silent |
+| Green, untouched, internal `{{PKG_SCOPE}}/*` | patch/minor | n/a | **Auto-merge**, silent — trusted |
+| Green, untouched | patch/minor | risky | Comment + label + NOTIFY |
+| major — local+CI green | analysis | **Verified**: comment + label + NOTIFY. Never merge |
+| major — we fixed it, CI green | analysis + fix | **Fixed**: comment + label + NOTIFY. Never merge |
+| major — can't fix | analysis + attempt | **Couldn't-fix**: comment + label + NOTIFY. Never merge |
+| Fixed by us, CI green | any | — | Comment + label + NOTIFY "fix ready" |
+| No CI / timeout | any | — | **Comment only** — no label, no NOTIFY (environmental) |
+| Already labeled | — | — | **Skip** |
+| `ERESOLVE` peer-dep, prerequisite bot PR exists | any | — | **Defer** `deferred-pending-#P` (fix-matrix.md) |
+
+## Step 4: NOTIFY events
+
+Fire on **every needs-human outcome** (auto-merges stay silent): fix-ready, couldn't-fix, every major (verified/fixed/couldn't-fix), risky patch/minor. Do **NOT** fire for `no-CI-deferred`, `skipped-labeled`, `skipped-closed`. Print one line per event:
+
+```
+MISTERPROPRE_NOTIFY_V1 {"v":1,"repo":"{{ORG}}/{repo}","pr":N,"url":"<pr-url>","outcome":"<outcome>","package":"<pkg>","bump":"<patch|minor|major>","message":"<one-line: what + action needed>"}
+```
+
+## Step 5: Iterate (catch newly-opened bot PRs)
+
+A run can take hours; bots open PRs meanwhile. Bounded loop, **MAX_ITERATIONS = 3**: after Step 2, re-run Step 1 discovery; filter out non-OPEN / labeled / already-processed PRs; if empty → stable, go to Step 6; else process the new ones (Step 2) and loop (≤3). If the cap is hit with PRs still pending, NOTIFY once ("iteration cap reached, re-run") and proceed.
+
+## Step 6: Final report + result line
+
+Print a per-PR outcome table (PR #, package, bump, iteration #, outcome ∈ {merged, fix-ready, major-verified, major-fixed, major-couldnt-fix, risky-handoff, no-CI-deferred, couldn't-fix, skipped-labeled, skipped-closed, deferred-pending-#P}) plus counts. Then emit **exactly one** final line:
+
+```
+MISTERPROPRE_RESULT_V1 {"v":1,"phase":"purge","kind":"DONE","counts":{"merged":M,"handedOff":H,"stillOpen":S}}
+```
+- `merged` = PRs auto-merged this run. `handedOff` = PRs labeled `purge:needs-human` this run. `stillOpen` = remaining open bot PRs not handed off (e.g. no-CI-deferred).
+- `kind` = `FAIL` only if the run could not complete (precondition failure / fatal error); otherwise `DONE`.
+
+## Anti-patterns
+
+- NEVER auto-merge a major / `0.x`-minor / risky bump, or any PR the skill modified.
+- **NEVER punt a major** with "review the release notes" — enumerate breakages + verified/fixed/blocked per item.
+- NEVER speculatively edit a green major to satisfy an untested changelog note — raise it as a "watch" in the comment.
+- NEVER treat a draft's stale `skipped` runs as passing; NEVER merge while any check is failing/pending.
+- NEVER comment on the auto-merge path. NEVER add `purge:needs-human` without a same-step comment explaining why.
+- NEVER `git checkout`/`switch` the clone; fixes happen in an isolated worktree.
+- NEVER use blanket workarounds (`legacy-peer-deps`, `--force`, `strict-ssl=false`) without explicit per-PR justification; prefer deferring to a prerequisite bot PR.
+- NEVER label on an environmental CI failure (`NO_CHECKS`/`TIMEOUT`) — comment only, retry next run.
+- NEVER `npm audit --fix`; NEVER hand-edit `package-lock.json`.
+- ALWAYS end with exactly one `MISTERPROPRE_RESULT_V1` line.

package/skills/dependabot-purge/references/fix-matrix.md.tmpl

@@ -0,0 +1,106 @@
+# Fix path — validation matrix & dependency-fix decision tree
+
+Load this when a PR's checks are FAILING or the PR conflicts with the base branch (Step 2-E).
+
+## Goal & budget
+
+Make the PR's CI green, then **hand off to a human** (never auto-merge a PR we modified). Budget: iterate **locally** until the validation matrix passes (minimize CI churn), then push and allow **up to 3 push/CI cycles**. If still red after that, or the fix needs a human product/code decision, give up and hand off.
+
+**Majors enter this engine proactively** (SKILL.md Step 3M) — driven by the breakage analysis, not only by a red CI. For a green major you still set up the worktree and run the matrix to **verify**; only a failing local check or CI run is a reproduced failure you then fix. **Never speculatively edit** to satisfy a changelog note that nothing tests — raise it as a "watch during review" risk in the handoff comment instead. Artifact-aware: a **GitHub Action** runs in GitHub CI (CI is its real test); a **Docker base image** verifies via `docker build`; an **npm package** verifies via the local matrix + CI.
+
+## Validation matrix (run in order, stop on first failure)
+
+Check each script exists in `package.json` first; if missing, mark `SKIPPED` and continue.
+
+| Step | Script | backend | frontend | qa |
+|------|--------|:-------:|:--------:|:--:|
+| 1 | `npm run lint`       | yes | yes | yes |
+| 2 | `npm run build`      | yes | yes | yes |
+| 3 | `npm run type-check` | yes | yes | yes |
+| 4 | `npm test`           | yes | yes | yes |
+| 5 | `npm run test:integ` | yes | no  | no  |
+
+**`test:integ` requires Docker.** Before step 5: `bash "$SKILL_DIR/scripts/ensure_docker.sh"`. Run `test:integ` **locally**; if Docker cannot start, mark it **BLOCKED** and hand off.
+
+A locally-green matrix is the gate to push. The real CI is the final authority — `bash "$SKILL_DIR/scripts/wait_checks.sh" {{ORG}}/{repo} {n}` judges it after each push (`$SKILL_DIR` = this skill's base directory).
+
+## Isolated worktree (always)
+
+Never `gh pr checkout` / switch branches in the clone — it may be dirty or on a feature branch. Work in a dedicated worktree (you start in the repo clone, your cwd):
+
+```bash
+git fetch origin {pr-head-branch}
+git worktree add -B {pr-head-branch} ~/.cache/misterpropre/purge-wt/{repo}-{n} origin/{pr-head-branch}
+cd ~/.cache/misterpropre/purge-wt/{repo}-{n}
+```
+
+(`{pr-head-branch}` = the PR's head ref, from `gh api repos/{{ORG}}/{repo}/pulls/{n} --jq .head.ref`.) Do all fix work here. **Clean up when done** (success, give-up, or error):
+
+```bash
+cd -   # back to the clone
+git worktree remove ~/.cache/misterpropre/purge-wt/{repo}-{n} --force
+```
+
+## Cross-PR peer-dep prerequisite detection (defer, do not patch)
+
+When `npm install`/`npm ci` fails with **`ERESOLVE`** naming a `peerDependency` conflict (e.g. *"{{PKG_SCOPE}}/design-system@13.25.0 requires i18next ^25.4.2 but i18next@26 is installed"*), **STOP** — do NOT reach for `--legacy-peer-deps`. Ask: is the missing version already on its way in another bot PR?
+
+1. **Identify the blocking package** — the one owning the unhappy `peerDependency` (read it from the npm error, e.g. `node_modules/{{PKG_SCOPE}}/design-system`).
+2. **Search the open bot PR list** for a PR upgrading that exact package to a compatible version:
+   ```bash
+   gh pr list --repo {{ORG}}/{repo} --state open \
+     --search '"{{PKG_SCOPE}}/design-system" in:title' \
+     --json number,title,author,headRefName,labels
+   ```
+   Filter to **bot PRs only** (`author.login` ∈ `{renovate[bot], dependabot[bot], app/renovate, app/dependabot}`).
+3. **If a bot prerequisite PR (`P`) EXISTS** → **defer the current PR** (`C`). Record `deferred-pending-#P`; do NOT comment/label/NOTIFY yet. Tear down `C`'s worktree, continue. Revisit `C` only after `P` is processed: if `P` merged and `C`'s CI now passes → proceed (D); else hand off `C` naming the chain (`#C blocked by #P`).
+4. **If NO bot prerequisite PR exists** → genuine block: comment naming the blocking peer + missing version, label `purge:needs-human`, NOTIFY "couldn't fix — peer dep conflict, no prerequisite PR". **Still do not push `legacy-peer-deps`.**
+
+**Cycle detection.** Maintain `deferred[C] = P`; if the chain loops, abort participants with one NOTIFY ("circular peer-dep deferral") + label each.
+
+## Per-PR diagnosis is mandatory (no recipe sharing)
+
+**Each PR is its own diagnosis.** Always: (1) clean isolated worktree off THAT PR's branch, (2) `npm install` + run the matrix to **reproduce THIS PR's failure**, (3) confirm the bump is the cause (`npm install {pkg}@{old} --no-save`, re-run), (4) only then design a fix. A fix that worked on an earlier PR is a **hypothesis**, never a recipe.
+
+### Banned blanket workarounds (require explicit per-PR justification)
+
+Do NOT introduce as a default fix: `legacy-peer-deps` / `npm install --legacy-peer-deps`, `npm install --force`, `strict-ssl=false`, `ignore-scripts=true`, `--passWithNoTests` / `--bail=false`. If one is the ONLY way to make CI pass, treat it as **needs a human decision** — comment what failed and why this masks vs fixes, hand off. **Do not push the workaround.**
+
+## Reproduce → fix loop
+
+1. In the worktree: `npm install` — clean baseline.
+2. Run the matrix to reproduce. For a major, run `type-check` first. Confirm the bump is the cause before editing.
+3. Read CI logs for parity if the matrix and CI disagree (`gh run view --log-failed`).
+4. Apply the smallest fix (mechanical first, then code adaptation). Re-run. Repeat until green.
+5. **Give-up trigger:** if the fix needs a domain decision (e.g. changing shared `{{PKG_SCOPE}}/types`, altering runtime behavior) or sprawls beyond a safe mechanical change, **stop and hand off** — including any fix that would need a banned workaround.
+
+## Dependency-fix decision tree (mechanical)
+
+Try in order, stop at first that works:
+1. **Lockfile-only:** `npm update {pkg}`; re-check `npm ls {pkg}`. Commit `package-lock.json` only.
+2. **Parent update:** bump the direct parent in `package.json` (`npm info {parent} version`), `npm install`, re-verify.
+3. **npm override (last resort):** add to `overrides` with a `>=` range (never pinned); scope for multi-major lines. Verify install; revert on peer conflict.
+
+NEVER `npm audit --fix`. NEVER hand-edit `package-lock.json`. Verify `npm install` after each change. One logical change at a time.
+
+## Code adaptation (breaking APIs)
+
+When a bump fails `build`/`type-check`/`test` from an API change, **edit the application code** to adapt (call sites, renamed imports, signatures, types, mocks, fixtures). Keep changes minimal + idiomatic. If adaptation balloons into a refactor or needs a product decision, stop and hand off.
+
+## Conflict resolution
+
+If the PR conflicts with `{base}` (default `{{BASE_BRANCH}}`): `git fetch origin {base}` then `git rebase origin/{base}` on the bot branch; resolve (favor the bot's intended version, keep base's other changes); `npm install`, run the matrix.
+
+## Push & CI cycles
+
+Once the matrix is locally green:
+1. `git add -A && git commit -m "fix(deps): adapt to {package} {version}"` (or `--amend` across cycles).
+2. `git push` (force-push only after a rebase: `git push --force-with-lease`).
+3. `bash "$SKILL_DIR/scripts/wait_checks.sh" {{ORG}}/{repo} {n}` → `PASS`=success; `FAIL`=fix more (max 3 cycles); `NO_CHECKS`/`TIMEOUT`=give-up endpoint.
+
+Do not trigger a bot rebase after pushing your fix — it could clobber it.
+
+## Endpoints
+
+- **Success (CI green):** emit a NOTIFY handoff line (`MISTERPROPRE_NOTIFY_V1`, "fix ready"), add the `purge:needs-human` label, leave the PR open. **Do not merge.**
+- **Give up (still red after 3 cycles, or needs a human decision):** add `purge:needs-human`, comment a brief reason, emit a NOTIFY "couldn't fix". Leave the branch pushed (the human inherits progress).

package/skills/dependabot-purge/scripts/ensure_docker.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Ensure the Docker daemon is running — `npm run test:integ` depends on it (local containers).
+# Launches Docker Desktop (macOS) or the docker service (Linux) if needed, then waits.
+# Exit 0 when Docker is ready; exit 1 if it cannot be started (caller: mark test:integ BLOCKED and hand off).
+set -uo pipefail
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "ERROR: docker CLI not found — cannot run integ tests." >&2
+  exit 1
+fi
+
+if docker info >/dev/null 2>&1; then
+  echo "Docker already running"
+  exit 0
+fi
+
+echo "Docker not running — launching..."
+case "$(uname)" in
+  Darwin) open -a Docker 2>/dev/null || open -a "Docker Desktop" 2>/dev/null || true ;;
+  *)      (sudo systemctl start docker 2>/dev/null || sudo service docker start 2>/dev/null) || true ;;
+esac
+
+# Wait up to ~150s for the daemon to accept connections.
+for _ in $(seq 1 75); do
+  if docker info >/dev/null 2>&1; then
+    echo "Docker is ready"
+    exit 0
+  fi
+  sleep 2
+done
+
+echo "ERROR: Docker did not become ready within ~150s. Start it manually and re-run." >&2
+exit 1

package/skills/dependabot-purge/scripts/wait_checks.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Wait for a PR's fresh CI checks and print a single verdict.
+# Usage: wait_checks.sh <owner/repo> <pr-number> [timeout-sec] [interval-sec]
+# Verdict (last line): PASS | FAIL | NO_CHECKS | TIMEOUT
+#
+# Uses the REST API (gh api) so it is immune to the `gh pr checks` cwd quirk.
+# Combines Check Runs (filter=latest) + the legacy combined Status.
+# `skipped` check runs are ignored (a draft gates CI jobs on draft==false; we wait
+# for the fresh post-ready runs). PASS requires >=1 real success and nothing
+# failed/pending.
+set -uo pipefail
+
+REPO="${1:?owner/repo required}"
+PR="${2:?pr number required}"
+TIMEOUT="${3:-1200}"   # 20 min
+INTERVAL="${4:-30}"
+GRACE="${GRACE:-25}"    # let a freshly-triggered run register before first verdict
+
+num() { local v; v="$(cat)"; [[ "$v" =~ ^[0-9]+$ ]] && echo "$v" || echo 0; }
+
+SHA="$(gh api "repos/${REPO}/pulls/${PR}" --jq '.head.sha' 2>/dev/null)"
+if [[ -z "${SHA:-}" ]]; then
+  echo "ERROR: could not resolve head sha for ${REPO}#${PR}" >&2
+  echo "NO_CHECKS"; exit 0
+fi
+
+echo "Waiting for checks on ${REPO}#${PR} (sha ${SHA:0:7}); timeout ${TIMEOUT}s..." >&2
+sleep "$GRACE"
+
+deadline=$(( $(date +%s) + TIMEOUT ))
+last_pending=0
+
+while :; do
+  cr="$(gh api "repos/${REPO}/commits/${SHA}/check-runs?filter=latest" 2>/dev/null)"
+  st="$(gh api "repos/${REPO}/commits/${SHA}/status" 2>/dev/null)"
+  cr="${cr:-{\"check_runs\":[]\}}"
+  st="${st:-{\"statuses\":[]\}}"
+
+  pend_cr=$(printf '%s' "$cr" | jq '[.check_runs[]? | select(.status!="completed")] | length' 2>/dev/null | num)
+  pend_st=$(printf '%s' "$st" | jq '[.statuses[]? | select(.state=="pending")] | length' 2>/dev/null | num)
+  fail_cr=$(printf '%s' "$cr" | jq '[.check_runs[]? | select(.conclusion as $c | ["failure","timed_out","cancelled","action_required","stale"] | index($c))] | length' 2>/dev/null | num)
+  fail_st=$(printf '%s' "$st" | jq '[.statuses[]? | select(.state=="failure" or .state=="error")] | length' 2>/dev/null | num)
+  ok_cr=$(printf '%s' "$cr" | jq '[.check_runs[]? | select(.conclusion=="success" or .conclusion=="neutral")] | length' 2>/dev/null | num)
+  ok_st=$(printf '%s' "$st" | jq '[.statuses[]? | select(.state=="success")] | length' 2>/dev/null | num)
+
+  P=$(( pend_cr + pend_st )); F=$(( fail_cr + fail_st )); S=$(( ok_cr + ok_st ))
+  last_pending=$P
+
+  if   [ "$F" -gt 0 ]; then verdict=FAIL; break
+  elif [ "$P" -gt 0 ]; then :              # still running -> keep waiting
+  elif [ "$S" -gt 0 ]; then verdict=PASS; break
+  fi                                       # else: no checks yet / only skipped -> keep waiting
+
+  if [ "$(date +%s)" -ge "$deadline" ]; then
+    [ "$P" -gt 0 ] && verdict=TIMEOUT || verdict=NO_CHECKS
+    break
+  fi
+  sleep "$INTERVAL"
+done
+
+# Human-readable summary to stderr
+printf '%s' "$cr" | jq -r '.check_runs[]? | "  - \(.name): \(.status)/\(.conclusion // "—")"' 2>/dev/null >&2
+printf '%s' "$st" | jq -r '.statuses[]? | "  - \(.context): \(.state)"' 2>/dev/null >&2
+
+echo "$verdict"
+[ "$verdict" = PASS ] && exit 0 || exit 0

package/skills/security-dependabot-fix/SKILL.md.tmpl

@@ -0,0 +1,171 @@
+---
+name: {{INSTALL_NAME}}
+description: "Fix Dependabot security alerts of ALL severities (Critical, High, Medium, Low) on a GitHub repository under the {{ORG}} org. Runs inside an isolated git worktree provided by misterpropre, implements targeted fixes (version bumps, parent updates, npm overrides), verifies each fix, opens/updates a PR, and emits a machine-readable result line. Use when: fix dependabot alerts, fix security vulnerabilities, patch npm dependencies, resolve CVEs. Invocation: /{{INSTALL_NAME}} <repo-name>"
+user-invocable: true
+---
+
+<!-- {{MANAGED_MARKER}} — generated from misterpropre's bundled template. Edits here are overwritten by `mrp skills install`; change the template in the misterpropre package instead. -->
+
+# Security Dependabot Fix (misterpropre)
+
+Fix open Dependabot security alerts of **all severities** for a `{{ORG}}` org repository. Each fix is one commit; iterate highest-severity first so the most important fixes land earliest in history.
+
+## Runtime contract (read first — this differs from a standalone skill)
+
+You are invoked **by the misterpropre orchestrator**, which has already prepared your environment:
+
+- Your **current working directory is an isolated git worktree** for the target repo, already checked out on the security-fix branch (`fix/dependabot-security-<date>`, branched from `{{BASE_BRANCH}}`), or on an existing automation PR's branch (update mode).
+- **Do NOT** `git clone`, `cd` elsewhere, `git fetch`/`checkout`/`switch`, or create/delete branches. Never touch `~/` checkouts. Operate **only** in the current directory on the current branch. The orchestrator owns branch lifecycle and worktree teardown.
+- When done you MUST print exactly one **machine-readable result line** (see the last section). The orchestrator's authoritative outcome comes from GitHub + git state; your line is a validated hint.
+
+## Input
+
+- **Argument**: `repo-name` — the GitHub repository name under the `{{ORG}}` org.
+- The org is always `{{ORG}}`.
+
+---
+
+## Workflow
+
+### Step 0: Verify npm Authentication
+
+The `{{ORG}}` org uses private `{{PKG_SCOPE}}/*` packages that require a valid npm token; without it `npm install` 404s and the run is blocked.
+
+```bash
+npm whoami
+```
+
+- Username printed → continue.
+- `401`/error → **STOP**, emit `MISTERPROPRE_RESULT_V1 {"v":1,"phase":"fix","kind":"FAIL","message":"npm auth"}` and report that npm auth must be refreshed.
+
+### Step 1: Fetch Alerts
+
+```bash
+gh api "repos/{{ORG}}/{repo}/dependabot/alerts?severity=critical,high,medium,low&state=open&per_page=100" --paginate \
+  --jq '[.[] | {number, pkg: .dependency.package.name, ecosystem: .dependency.package.ecosystem, manifest: .dependency.manifest_path, relationship: .dependency.relationship, severity: .security_advisory.severity, summary: .security_advisory.summary, cve: .security_advisory.cve_id, ghsa: .security_advisory.ghsa_id, patched: .security_vulnerability.first_patched_version.identifier, range: .security_vulnerability.vulnerable_version_range}]'
+```
+
+Record the initial alert count broken down by severity. If zero alerts → report "No open security alerts found", emit the `NO_ALERTS` result line, and stop. Print a summary table before proceeding.
+
+### Step 2: Prepare (worktree-aware)
+
+You are already in the worktree on the correct branch — **do not change branches**. Just establish a clean baseline:
+
+```bash
+npm install
+```
+
+If install fails on a private `{{PKG_SCOPE}}/*` 404 → that's an npm-auth problem (Step 0). Otherwise note the error for the report.
+
+### Step 2.5: Classify Repo Type
+
+Select the validation matrix in Step 6:
+
+- Suffix `-back` → **backend**; `-front` → **frontend**; `-qa` → **qa**.
+- No matching suffix → classify by inspecting `package.json` scripts (presence of `test:integ`/`lint:cfn` ⇒ backend; `lint-style` ⇒ frontend); if still ambiguous treat as **backend** and note the assumption in the report.
+
+### Step 2.6: Capture the validation baseline (before any fixes)
+
+Run the Step 6 validation matrix **now**, on the unmodified worktree, using the Step 6 execution rules (`CI=true`, `timeout`, jest `--forceExit`, Docker-ensure before `test:integ`). Record each check's PASS/FAIL and, for `type-check`, the **error count**. This is the **BASELINE**. Step 6 blocks only on checks that get **worse** than this baseline.
+
+### Step 3: Classify Alerts
+
+Group by severity (critical → high → medium → low), then by package. Process top-down. **Deduplicate**: one fix per package; track which alert numbers each fix resolves.
+
+**Outcome classes:** `FIXED`, `UNFIXABLE` (no patched version), `FAILED` (broke something in this repo's own control — blocks the gate), `BLOCKED_UPSTREAM` (broke an internal `{{PKG_SCOPE}}/*` lib this repo only consumes — does NOT block; needs an upstream release). Detect `BLOCKED_UPSTREAM` when the regression trace points under `node_modules/{{PKG_SCOPE}}/...`, an `ERESOLVE` peer conflict is declared by a `{{PKG_SCOPE}}/*` package, or the vulnerable transitive only arrives via a `{{PKG_SCOPE}}/*` parent still pinning the bad range.
+
+### Step 4: Fix Decision Tree
+
+For each vulnerable package:
+
+**A. No patched version (`patched` is null)** → mark **UNFIXABLE** (record pkg, severity, advisory, CVE/GHSA).
+
+**B. Direct dependency (`relationship == "direct"`)**
+1. Edit the relevant `package.json` (use `manifest` path); preserve the `^`/`~`/pinned prefix. Flag major-version crossings in the report.
+2. `npm install`; verify with `npm ls {package}` (installed ≥ patched).
+3. If install fails, revert; mark **BLOCKED_UPSTREAM** if the blocker is `{{PKG_SCOPE}}/*`, else **FAILED**.
+
+**C. Indirect/transitive** — try in order, stop at first success:
+1. **Lockfile-only (preferred):** `npm update {pkg}`; re-check `npm ls {pkg}` all ≥ patched → commit `package-lock.json` only. No override, no `package.json` change.
+2. **Parent update:** bump the parent in `package.json` (`npm info {parent} version`), `npm install`, re-verify.
+3. **Override (last resort):** add to `package.json` `overrides` (`">={patched}"`; use scoped/range overrides for multi-major lines). `npm install`, verify; on peer conflict revert and classify FAILED/BLOCKED_UPSTREAM.
+
+Prefer lockfile-only updates: overrides add maintenance surface and can silently violate peer requirements.
+
+### Step 5: Apply and Commit Each Fix
+
+Per successful fix: stage `package.json` + `package-lock.json`, commit `fix(security): update {package} to {version} ({CVE-ID})`. One commit per fix.
+
+### Step 6: Final Verification
+
+1. `npm install` (lockfile integrity).
+2. `npm audit --audit-level=low` (count remaining).
+3. **Validation matrix** by repo type; run in order, **stop on first failure**; missing script ⇒ `SKIPPED`.
+
+   | Step | Script | Backend | Frontend | QA |
+   |------|--------|:-------:|:--------:|:--:|
+   | 1 | `npm run lint`       | ✅ | ✅ | ✅ |
+   | 2 | `npm run lint-style` | ❌ | ✅ | ❌ |
+   | 3 | `npm run lint:cfn`   | ✅ | ❌ | ❌ |
+   | 4 | `npm run build`      | ✅ | ✅ | ✅ |
+   | 5 | `npm run type-check` | ✅ | ✅ | ✅ |
+   | 6 | `npm test`           | ✅ | ✅ | ✅ |
+   | 7 | `npm run test:integ` | ✅ | ❌ | ❌ |
+
+   Run each in the **foreground** with a hard timeout; never background-and-poll:
+   ```bash
+   CI=true timeout 1500 npm run <script> >/tmp/val.log 2>&1; ec=$?; tail -n 40 /tmp/val.log
+   ```
+   `CI=true` makes vite/jest/react-scripts run once. For jest `test`/`test:integ` append `--forceExit`. Interpret `ec`: `0`=PASS, `124`=timeout→FAIL, other non-zero=FAIL. Before `test:integ` (backend) ensure Docker is up; if unavailable, record FAIL ("Docker unavailable").
+
+4. **Compare each check to the Step 2.6 BASELINE — block only on regressions** (passed at baseline, now FAILs; or type-check error count increased). Pre-existing failures are `PRE-EXISTING`, do not block.
+5. **Per-fix regression isolation:** if a check regressed, bisect to the offending fix. If its root cause is under `node_modules/{{PKG_SCOPE}}/...` → revert ONLY that fix, mark its alert `BLOCKED_UPSTREAM`, re-run. If in this repo's own code → that fix is `FAILED` (blocks).
+6. Proceed if **no regressions vs baseline** and **no `FAILED`** (`BLOCKED_UPSTREAM`/`UNFIXABLE`/`SKIPPED`/pre-existing are fine).
+
+### Step 7: Generate Report
+
+Print the standard report (Summary / Fixed / Unfixable / Failed / Blocked upstream / Verification), with repo `{{ORG}}/{repo}`. Count fixed alerts by severity for the result line.
+
+### Step 8: Push and Open/Update the PR
+
+Gate — proceed if **either**: (A) pure success (no regressions, zero FAILED/BLOCKED_UPSTREAM), or (B) partial success — ≥1 fix is `FIXED` and the worktree is regression-free vs baseline (with FAILED fixes reverted). `FAILED`/`BLOCKED_UPSTREAM`/`UNFIXABLE` are documented but do NOT block. The ONLY blocker is an **unreverted regression** vs baseline.
+
+**If the gate passes:**
+```bash
+branch="$(git rev-parse --abbrev-ref HEAD)"            # the worktree's current branch
+git push -u origin "$branch"
+existing="$(gh pr list --repo {{ORG}}/{repo} --head "$branch" --state open --json url --jq '.[0].url')"
+if [ -z "$existing" ]; then
+  gh pr create --repo {{ORG}}/{repo} --base {{BASE_BRANCH}} --head "$branch" --title "fix: security" --body ""
+fi
+```
+Title exactly `fix: security`; empty body; ready for review (no `--draft`); no reviewers/assignees/labels. A brand-new PR ⇒ `NEW_PR`. Pushing commits onto a branch whose PR already existed ⇒ `UPDATED_PR`; if nothing new was needed ⇒ `PR_UP_TO_DATE`.
+
+**If nothing is shippable** (every alert UNFIXABLE/BLOCKED_UPSTREAM, or all attempts reverted) and the tree is clean → push nothing ⇒ `NO_FIXABLE`.
+
+**If an unreverted regression remains** (a clean-looking fix actually broke something) → do NOT push; leave the worktree as-is ⇒ `LEFT_LOCAL`.
+
+---
+
+## Machine-readable result (REQUIRED — last line of output)
+
+Print **exactly one** line, as the final output, framed and versioned:
+
+```
+MISTERPROPRE_RESULT_V1 {"v":1,"phase":"fix","kind":"<KIND>","prUrl":"<url>","counts":{"fixed":N,"critical":c,"high":h,"medium":m,"low":l}}
+```
+
+- `kind` ∈ `NEW_PR | UPDATED_PR | PR_UP_TO_DATE | NO_ALERTS | NO_FIXABLE | LEFT_LOCAL | FAIL`.
+- `prUrl` only for the PR kinds (omit otherwise). `counts` = alerts actually fixed this run by severity (omit for NO_ALERTS/FAIL).
+- One line, single-line JSON, no trailing prose after it. The orchestrator reconciles this against GitHub + git; if you can't determine a field, omit it rather than guessing.
+
+## Anti-Patterns
+
+- **NEVER** clone, `cd` out of the worktree, fetch, or create/switch/delete branches — the orchestrator owns all of that.
+- **NEVER** push/open a PR with an **unreverted regression** vs the Step 2.6 baseline.
+- **DO** ship the clean fixes even if some are `FAILED`/`BLOCKED_UPSTREAM`/`UNFIXABLE` (≥1 `FIXED`, tree regression-free).
+- **NEVER** classify a regression rooted in `node_modules/{{PKG_SCOPE}}/...` as `FAILED` — that's `BLOCKED_UPSTREAM`.
+- **NEVER** add a PR body/description; title-only `fix: security`. Never draft, never add reviewers/assignees/labels.
+- **NEVER** `npm audit --fix`; **NEVER** hand-edit `package-lock.json`; **NEVER** dismiss alerts via the API.
+- **NEVER** skip `npm install` verification after each fix. **ALWAYS** use `>=` for override versions.
+- **ALWAYS** end with exactly one `MISTERPROPRE_RESULT_V1` line.