community-sweep skill

Community Sweep

Grow the claude-mem community by merging people in. Every valuable contribution lands as the contributor: their PR, their name as the commit author on main. A PR that is only partly right gets finished on their branch instead of rejected. Issues get the same treatment, so the person who reported a bug and the person who fixed it both hear about it, by name.

This is the protocol from the 2026-09-30 open-PR merge sweep, which took 257 open PRs to 46 and merged 143 contributor PRs from 87 authors with their authorship intact. It is written down so every new batch of PRs and issues gets handled the same way.

The owner's merge philosophy

1. Merge as many valuable contributions as possible. This is looser than the Merge Clinic (#3372, docs/merge-rubric.md). Opt-in features are welcome, as are extensibility (providers, hosts, hooks, settings knobs) and anything that cuts token spend (bounding, batching, dedup, filtering).
2. Finish, don't reject. If the intent is right but the fix is partial or buggy, finish it on the contributor's branch, or land only its additive piece (a trim). Either way the credit stays with them.
3. No band-aids, but no bleeding. A fix walks the issue down to its root cause. A band-aid that stops active user harm ships only with a written post-plan: the root-cause follow-up, specified well enough to execute.
4. The contributor is the author. A merge that puts the maintainer's name on someone else's work is a failed merge.
5. Respect the hosted-service boundary (step 2). A PR may not change how cmem.ai cloud sync or the gateway's sign-in and trial path behave. You decide: trim or rework that part out and land the rest, or decline it with the reason.
6. Security and privacy regressions block a merge. That covers secrets in logs, data sent to third parties, and injection.
7. Critical bug fixes ship now. A PR that fixes a break users are hitting goes out right away, so nobody's service stays interrupted: sign-in or activation that errors, a worker that won't start, hooks that fail, capture or search that stops working, data loss. It lands first in the run and a patch release follows (step 3). It never waits for the owner, including when the broken path is cmem.ai sign-in, sync or the gateway. The boundary in step 2 covers changes to how those paths behave, not fixes that make them work again. On 2026-11-07 the owner was wrongly asked about #5455, which fixed Pro sign-in returning 500 on every install.
8. Nothing needs the owner. The owner set this on 2026-11-07. Every PR and issue in a sweep gets decided and carried through by you: merge, close, release, X post. The report says what you decided and why. It never asks the owner a question or lists decisions for them.

Count humans, not tools. A PR written with Claude, Codex, Cursor or Copilot is credited to the human who opened it. Bot PRs (PostHog, Copilot agent, Dependabot) land on merit, but they never go on the roster.

Private state: never commit, never upload

Run state lives in the main checkout's gitignored .scratch/, so every worktree shares it:

MAIN_CHECKOUT="$(cd "$(git rev-parse --git-common-dir)/.." && pwd)"
STATE="$MAIN_CHECKOUT/.scratch/community"
RUN_ID="CS-$(date -u +%F)"; RUN="$STATE/runs/$RUN_ID"; mkdir -p "$RUN"

To append a ledger row (tab-separated; PR and issue numbers share one namespace):

printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -u +%FT%TZ)" <number> "$RUN_ID" <action> <merge_sha|-> <author> <coauthors|-> "<one-line note>" >> "$STATE/ledger.tsv"

• Actions for PRs: merged, closed, blocked, skipped; for the owner's PRs, also experimental, and approved, which the owner writes to take a PR out of experimental. Older runs also wrote held, and approved for owner sign-offs.
• Actions for issues: issue-closed, issue-answered, issue-routed. Older runs also wrote issue-held.
• New ledger: if ledger.tsv doesn't exist, create it with the header ts pr phase action mergesha prauthor coauthors note (tab-separated).

1. Take stock

gh pr list --repo thedotmack/claude-mem --state open --limit 500 --json number,title,author,isDraft,createdAt,updatedAt,mergeable,mergeStateStatus,maintainerCanModify,headRefName,headRepositoryOwner,baseRefName,additions,deletions > "$RUN/open-prs.json"
gh issue list --repo thedotmack/claude-mem --state open --limit 500 --json number,title,author,createdAt,updatedAt,labels,comments > "$RUN/open-issues.json"

Put every open PR in exactly one bucket, using its last ledger row. Use the first bucket that matches:

For issues, skip the maintainer-authored ones: the [plan-NN] masters and the Merge Clinic. Triage every other open issue that:

• has no ledger row, however old it is (a run that stopped early leaves these behind);
• has issue-held as its last row (written before 2026-11-07): triage it from scratch this run, like a held PR;
• was updated after its own last ledger row.

On a first run, that is all of them.

Test baseline. Take it once per run, before landing anything. Use a clean origin/main worktree and the same Bun as CI (bun-version: latest), because an older local Bun can fail subprocess tests that CI passes. If local Bun is behind, run every suite in the run (baseline, per-PR and gate) as npx -y bun@ test …. npm view bun version gives the latest version.

npm install --no-audit --no-fund && npm run build
env -u CLAUDE_MEM_LLM_TIMEOUT_MS bun test tests > "$RUN/baseline-suite.log" 2>&1; echo "suite exit $?"
grep -E '^\(fail\)' "$RUN/baseline-suite.log" | sed -E 's/ \[[0-9.]+m?s\]$//' | sort -u > "$RUN/baseline-failures.txt"
tail -n 40 "$RUN/baseline-suite.log" | grep -E '^ *[0-9]+ pass$|^ *[0-9]+ fail$|^Ran [0-9]+ tests across'

The last command must print the suite's own summary: N pass, N fail and Ran N tests across M files, with M close to the number of test files. If it prints nothing, the run died before finishing (a crash, a timeout, a missing dependency) and an empty baseline-failures.txt means nothing. Stop, fix the cause, and take the baseline again; never land PRs against an incomplete one. A nonzero exit on its own is not that: failing tests exit nonzero, and some Bun versions crash at exit after printing the summary. The sed drops each failure's timing so the lists compare line for line.

2. Triage each new PR (read-only)

gh pr view <N> --repo thedotmack/claude-mem --json title,body,author,headRefOid,headRefName,headRepositoryOwner,maintainerCanModify,mergeable,mergeStateStatus,isDraft,closingIssuesReferences,commits,files
gh pr diff <N> --repo thedotmack/claude-mem
gh pr checks <N> --repo thedotmack/claude-mem
gh api repos/thedotmack/claude-mem/pulls/<N>/comments --paginate   # inline review findings (Greptile, Cursor Bugbot, CodeRabbit)
gh api repos/thedotmack/claude-mem/issues/<N>/comments --paginate  # the conversation

Read main's code with git show origin/main:. Leave generated bundles out of diff sizing (the list is in step 3); they're noise and get stripped at merge. If the PR maps to a plan master (plans/NN-*.md), read that section first. A PR that implements the master's intended fix is a strong candidate. A PR that contradicts the master needs a reason.

Evidence per PR:

• Facts: author, draft, mergeable, maintainerCanModify, CI state, non-bundle diff size, linked issues.
• CI: a failure that also shows up on main's recent runs (gh run list --repo thedotmack/claude-mem --branch main --limit 5) is not the PR's.
• Root cause and change: the root cause in one or two lines, and what the PR changes.
• Still needed on main? Cite file:line or a commit as evidence.
• Review findings: unresolved bot and maintainer findings (P0/P1/P2), and whether the contributor addressed them.
• Quality: tests added, and whether it's a band-aid.
• Boundary flags.
• Overlaps: other PRs on the same area, including maintainer PRs.
• Verdict and confidence.

Verdicts (exactly one per PR):

The owner's own PRs (author thedotmack)

The owner's PRs go through the same triage and landing as everyone's.

• Experimental. The owner marks a PR experimental in the ledger. It stays out of the sweep until the owner takes it out of experimental by writing an approved row, which puts it in the Approved bucket; each run, list any new activity on it.
• A boundary change in the owner's own PR is the owner's intent, so it isn't trimmed for that reason. Check that it doesn't clash with a boundary change already on main, and resolve any clash yourself.
• No thank-you comment. After a merge, post a 1–3 bullet note only if we pushed changes (what we changed and why). Don't add the owner to the roster.

The hosted-service boundary (verdict BOUNDARY)

claude-mem is open source. cmem.ai is the hosted service: cloud sync, plus the inference gateway with its sign-in and trial. A PR must not do any of the following as written. Trim or rework that part out and land the rest, or decline it:

1. Changes the installer's provider screen or defaults, exempts a provider from sign-in, or changes the cmem.ai sign-in, trial or activation steps (src/npx-cli/commands/install.ts, src/npx-cli/cmem-memory-credentials.ts, src/npx-cli/cmem-pro-costs.ts).
2. Lets the cmem.ai memory key reach any host but the gateway, or loosens gateway detection (src/shared/cmem-gateway.ts, the keysForEndpoint lock).
3. Routes gateway quota or key failures to another provider before the gateway's own trial-expiry fallback runs (src/services/worker/provider-dispatch.ts).
4. Removes, hides or defaults off a cmem.ai notice or link: installer next steps, the session-start line, the context banner, the viewer header, or renewal notices. Their copy lives in src/shared/pro-promo.ts.
5. Adds another sync, backup or remote-memory destination, or a turnkey hosted port of the server runtime.
6. Changes cloud-sync semantics: data loss, a weaker ack contract, or sync without entitlement (src/services/sync/, services/sync-api/).
7. Adds a new default-on path that spends model tokens, such as extra observer calls, backfills or new ingestion. The same feature as an opt-in that defaults off is fine.

These are not conflicts, so judge them on merit: opt-in bring-your-own providers, hosts and knobs that leave the gateway path first; token-spend optimizations; correct fixes to our own sync client; IDE and host integrations; and fixes to the self-hosted server runtime. Supporting a new IDE or host is never a product call: the goal is to support every IDE, so a new adapter or install --ide gets judged on merit, and an issue asking for one gets a go-ahead. A new provider preset never goes above cmem.ai and never edits the installer, sign-in or cost files. A fix that makes a broken boundary path work again (sign-in that 500s, sync that stalls, a gateway call that crashes) is not a boundary change: it is a critical fix (philosophy 7), so land it. If the fix also changes what the path does (different steps, defaults, notices or entitlement), land the fix and trim that change. If you're unsure, take the reading that leaves cmem.ai's path unchanged, land it, and say in the report what you decided.

The live-only observer rule (never MERGE as-is)

The local observer is live-only. The owner set this on 2026-11-03, and AGENTS.md and docs/architecture/observer-lifecycle.md on main hold the full contract. Read both before triaging any PR that touches capture, the hook spool, SessionMessageBuffer, GeneratorExitHandler, getResumableSessionIds, abort categories, resume timers or provider cooldowns.

• A PR that keeps, persists, re-queues or automatically resumes observer inference work after quota, auth, a stall, an outage or a restart breaks the rule. That includes resuming on "proof of recovery", such as a later successful store, a login or a quota reset. Verdict REWORK to discard the work through discardBufferedWork, or DECLINE when nothing else is left. Never MERGE it as-is, however good its tests are.
• Tests that prove a queue drains don't count. The PR must show an outage can't cause later inference spend nobody asked for.
• Main's code is not the authority when it contradicts AGENTS.md. Preserve-and-resume code still on main is a bug waiting for removal. It is not a reason to hold the owner's PR that removes it. #5383 was merged against this rule on 2026-11-05, and on 2026-11-06 the owner's fix #5347 was wrongly held as "overtaken" by it.

3. Land as the contributor

Work in your own worktree, never the user's current one: an Agent with isolation: "worktree", or git worktree add --detach "$MAIN_CHECKOUT/.claude/worktrees/community-" origin/main. Then run npm install --no-audit --no-fund.

gh pr view <N> --repo thedotmack/claude-mem --json state,isDraft,mergeable,baseRefName,headRefName,maintainerCanModify   # merged or closed meanwhile? ledger it `skipped`
gh pr edit <N> --repo thedotmack/claude-mem --base main          # only if the base isn't main
gh pr checkout <N> --repo thedotmack/claude-mem --branch pr-<N>  # sets the push remote to their fork
git merge --no-edit origin/main                                   # a merge commit; never rebase their commits

Generated bundles never land from a PR; they're rebuilt at release. The generated set is what scripts/build-hooks.js and scripts/build-viewer.js write. If the list below looks stale, re-read those two scripts:

• plugin/scripts/{worker-service,hook-service,server-service,mcp-server,context-generator,context-read-worker,work-view-read-worker,transcript-watcher,claude-mem-launcher,ensure-launcher}.cjs and their .map files;
• plugin/sqlite/**;
• plugin/ui/viewer-bundle.js, plugin/ui/viewer.html, plugin/ui/tv.html, plugin/ui/work-view/** (the Vite build of src/ui/my-work), and the fonts and icons copied into plugin/ui/;
• plugin/package.json;
• plugin/skills/request-progress/scripts/request-groups.mjs.

If the PR changed any of them, restore them with git checkout origin/main -- (or git rm any the PR added) and commit chore: drop generated bundles (rebuilt at release). If the PR edited only a copy (say plugin/ui/viewer.html), move the edit to its source under src/. Hand-written files under plugin/ stay: plugin/scripts/{bun-runner.js,statusline-counts.js,version-check.js,worker-wrapper.cjs,qoder-hook-launcher.cjs}, hooks, skills, modes and manifests.

Apply the verdict. MERGE needs nothing more. For REWORK and TRIM, follow the gap list (step 4). Our commits use conventional messages and end with the attribution trailers your session specifies.

Verify on the exact head you will merge:

1. Run npm run typecheck.
2. Commit everything first. Then run npm run build (the bundle-size guardrail) and leave its output in place for steps 3–5, so tests that load built bundles run the PR's code, not main's.
3. Run the PR's targeted tests.
4. For any non-trivial change, run env -u CLAUDEMEMLLMTIMEOUTMS bun test tests and compare it with $RUN/baseline-failures.txt. For a failure that isn't in the baseline, re-run that file alone first. If it passes alone and in CI, it was load from parallel suites. If it still fails, it's the PR's to fix.
5. If openclaw/ is touched, run bun test openclaw.
6. Then run git checkout -- plugin/ and git clean -fd -- plugin/, so build output is never committed. Do this before any further commit too. The checkout alone leaves untracked output behind, such as plugin/scripts/work-view-read-worker.cjs and plugin/ui/work-view/assets/*. Stage files by name, not with git add -A.
7. A PR that adds a SessionStore migration takes the next free schema version on main at merge time. Two PRs raced for one version during the sweep.

Push to their branch, which is needed only if you merged main with conflicts or added commits. Never force-push.

remote=$(git config branch.pr-<N>.pushRemote || git config branch.pr-<N>.remote)
head=$(git config branch.pr-<N>.merge); head=${head#refs/heads/}
git push "$remote" "HEAD:$head"    # a bare `git push` is refused: the local name pr-<N> differs from their branch

If the push is rejected as non-fast-forward, they pushed meanwhile. Run git pull --no-rebase "$remote" "$head", re-verify and push again. If their new head already does what you did, drop yours.

CI.

• First-time contributors' runs sit in action_required. Read the whole diff for anything that executes in CI (workflows, package scripts, postinstall, tests that shell out). Then approve every waiting run for the PR head except Claude Code: CI and Windows always, plus Media native runtime and Native ODS integration when the PR's paths start them. Look them up by head SHA: gh run list --branch misses fork PRs.

sha=$(gh pr view <N> --repo thedotmack/claude-mem --json headRefOid --jq .headRefOid)
  gh api "repos/thedotmack/claude-mem/actions/runs?head_sha=$sha" --jq '.workflow_runs[] | select(.conclusion=="action_required" and .name!="Claude Code") | "\(.id) \(.name)"'
  gh api -X POST repos/thedotmack/claude-mem/actions/runs/<id>/approve   # once per id listed

• Never approve CI for SPAM o