feat: sharded in-memory stores + #[concurrent_cached] default

.agents/skills/pr-review/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: pr-review
+description: Targeted, read-only review of a PR or checked-out branch. Acquires the diff (a PR number, or the current branch vs origin/master), spawns an independent code-review sub-agent and a library-consumer sub-agent in parallel, then aggregates their findings into a single report with severity and a valid / already-fixed / invalid verdict for each. Read-only — it does not edit files, commit, push, or touch the GitHub PR conversation. The review sub-agents default to Sonnet but can be overridden per run (e.g. to opus). Use when asked to "review this PR", "review the branch", "what's wrong with this diff", "do a code review", or "review with opus". For the full review → fix → push → resolve loop, use `pr-cycle` (which delegates its review step here).
+allowed-tools: Bash, Read, Agent
+---
+
+# PR Review
+
+Produce a fresh, read-only review of a PR or a checked-out branch and report the
+findings. This is the "review" half of the PR workflow, extracted so it can be run
+on its own. The orchestrator skill `pr-cycle` calls this skill to obtain its local
+findings, then goes on to address, push, and resolve them.
+
+## Scope — what this does and does not do
+
+**Does:** acquire the diff, spawn the two read-only review sub-agents, evaluate
+their findings, and report them with severity and a verdict.
+
+**Does NOT:** edit files, run `make ci`, regenerate the README, commit, or push; and
+it does **not** interact with the GitHub PR conversation — it does not read existing
+PR comments/threads, resolve or minimize them, edit the PR body, or re-request
+Copilot review. Those belong to `pr-cycle`. This skill only generates a fresh
+agent-based review of the code itself.
+
+This skill is purely advisory: its output is a findings report for a human (or for
+`pr-cycle`) to act on. It applies no changes.
+
+## Model tiers
+
+| Tier | What | Step | Model |
+|------|------|------|-------|
+| 1 — cheap delegation | Read-only review sub-agents | 2 | Sonnet (pinned in agent def; overridable per-run, e.g. to opus — see [Input](#input)) |
+| 2 — judgment core | Classify findings into valid / already-fixed / invalid | 3, 4 | session model (use Opus for the verdict pass) |
+
+## Input
+
+A target and an optional review-agent model override, in any order.
+
+- **Target**: either a **PR number**, or **nothing** (review the current checked-out
+  branch). If a PR number is omitted you may infer one from the current branch with
+  `gh pr view --json number` (run with the sandbox disabled — see below), but a PR is
+  **not required**: a plain checked-out branch is reviewed by diffing against
+  `origin/master`.
+- **Review-agent model**: the model used by the two sub-agents (`pr-code-reviewer`,
+  `pr-consumer-reviewer`) **defaults to `sonnet`**, but can be overridden. If the input
+  names a model (e.g. "review with opus", "opus reviewers", "model=opus"), pass that
+  model to the Agent tool's `model` parameter when spawning **both** sub-agents in
+  step 2. With no override, omit `model` so each agent uses its pinned Sonnet default.
+
+Announce the resolved target and review-agent model at the start — e.g. "Reviewing
+the current branch with **opus** reviewers" or "Reviewing PR #264 with Sonnet
+reviewers" — before spawning anything.
+
+## Steps
+
+### 1. Acquire the diff
+
+The diff is `git diff origin/master`, which works for any checked-out branch whether
+or not it has a PR:
+
+```bash
+git diff origin/master
+```
+
+If you are targeting a specific PR, the `pr-cycle` helper prints the identical diff
+and is equivalent:
+
+```bash
+.agents/skills/pr-cycle/pr.py PR_NUMBER diff
+```
+
+Capture the full diff text — it is fed verbatim to both sub-agents.
+
+### 2. Spawn two independent sub-agents in parallel
+
+**Agent A — code reviewer**: Spawn with the `pr-code-reviewer` agent type. Prompt must
+include:
+- The PR number (or branch name, if there is no PR)
+- The full diff (from step 1)
+
+**Agent B — library consumer**: Spawn with the `pr-consumer-reviewer` agent type. Prompt
+must include:
+- The PR number (or branch name)
+- The full diff
+- The current `src/lib.rs` doc comments and `README.md` (or relevant excerpts covering
+  the changed APIs)
+
+Both agents are read-only (no Edit/Write tools) and carry their full rubrics in their
+agent definitions — do not re-specify the rubric in the prompt.
+
+**Model override:** if the input requested a review-agent model (see [Input](#input)),
+pass it to the Agent tool's `model` parameter on **both** spawns (e.g. `model: "opus"`).
+With no override, omit `model` so each agent uses its pinned Sonnet default.
+
+Launch both agents in parallel. Wait for both to complete before proceeding.
+
+### 3. Evaluate all findings
+
+Collect both sub-agent reports. For each finding, assign a verdict and explain your
+reasoning:
+
+- **Valid** — the concern is real and the code should change.
+- **Already fixed** — the concern was valid in principle but the current code already
+  handles it (the reviewer was working from a partial view).
+- **Invalid** — the finding is incorrect or environment-specific (e.g. a rustc version
+  mismatch on trybuild golden files, or a "missing" feature gate that is actually
+  present).
+
+This verdict pass is the judgment core; run it on the session model (use Opus). Do not
+soften or pad — an invalid finding called valid sends `pr-cycle` (or a human) chasing a
+non-issue.
+
+### 4. Report
+
+Present a single consolidated report:
+
+- The target reviewed (PR number or branch name) and the review-agent model used.
+- **Code-reviewer findings**: total count, broken down by severity (high / medium / low),
+  and by verdict (valid / already-fixed / invalid).
+- **Consumer-reviewer findings**: the same breakdown.
+- For each **valid** finding: a one-line summary, the `file:line` (or area), and why it
+  matters — enough that `pr-cycle` or a human can act on it without re-reading the agent
+  output.
+- For each **invalid** or **already-fixed** finding: a one-line note on why it was ruled
+  so.
+- A closing one-line verdict: is the branch/PR clean, or are there valid findings to
+  address (and how many high/medium)?
+
+Do not apply any fix. If the caller wants the findings addressed and pushed, that is
+`pr-cycle`'s job.

.agents/skills/release/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: release
+description: Prepare a release (bump versions across all Cargo.toml files, update CHANGELOG.md, refresh the migration guide, regenerate README, commit), or run a pre-release review. The `review` option kicks off a consistency review and an API-examination review to surface lingering inconsistencies and a categorized list of breaking and non-breaking improvements before you cut the release — advisory only, it changes nothing. Use when asked to "cut a release", "bump the version", "prepare a release", "release X.Y.Z", or "do a release review" / "review for release". Takes a version string (e.g. `/release 1.2.0`) or `review` as the argument.
+---
+
+# Release
+
+Prepare a new release by bumping versions and updating the changelog — or, with the
+`review` option, run a pre-release audit that surfaces inconsistencies and improvement
+ideas without changing anything.
+
+## Input
+
+The argument selects the mode:
+
+- **`review`** (or "release review", "review for release", "pre-release review") — run the
+  **Release review** below. This is advisory only: it bumps nothing, edits no files, and
+  makes no commit. Run it *before* cutting a release.
+- **A version string** (e.g. `1.2.0`) — run the **Version bump** flow (the numbered steps).
+  If no argument is given and the intent is clearly to cut a release, ask which version.
+
+If the user asks for a release review and then to proceed, run the review first and the
+version bump second.
+
+## Release review
+
+A pre-release audit. Run it **before** cutting a release — especially a major version,
+since a major bump is the only window in which breaking API changes are acceptable. It
+**does not** bump versions, edit the changelog/README, or commit anything; it produces a
+report. It kicks off two complementary reviews, then synthesizes them.
+
+### A. Consistency review
+
+Audit the public surface for lingering inconsistencies across the **whole crate**, not
+just the latest diff. Scope it to everything accumulated since the last released tag:
+
+```bash
+git describe --tags --abbrev=0    # last released tag
+git diff "$(git describe --tags --abbrev=0)"..HEAD --stat   # what this release will ship
+```
+
+Check for:
+- **Naming parity** — do sibling types/methods share vocabulary? (e.g. `max_size` vs
+  `size`, `with_*` constructors, `try_with_*` fallible variants, `cache_*` method
+  prefixes). Flag any odd-one-out.
+- **Builder / constructor symmetry** — does every store with a builder expose the same
+  setters where they make sense? Does each family (plain vs sharded, LRU vs TTL) have
+  parallel constructors?
+- **Trait-method parity** — do the sync / async / sharded variants of a trait expose the
+  same method set with consistent signatures (`&self` vs `&mut self`)?
+- **Feature-gate symmetry** — is each public item gated behind exactly the features it
+  needs, and are paired items gated consistently?
+- **Doc / CHANGELOG / migration-guide alignment** — do the docs, the `[Unreleased]`
+  CHANGELOG section, and the migration guide accurately describe the shipped API (named
+  types, signatures, attribute names, feature gates)?
+
+Delegate the correctness/idiom sweep to a `pr-code-reviewer` sub-agent fed the full
+release diff, and reason through the cross-type parity items yourself — they need a
+whole-surface view the diff alone does not give.
+
+### B. API examination review
+
+Run the `consumer-experience-review` skill. It builds a throwaway external consumer that
+depends on the crate the way a real user would and surfaces API gaps, naming
+inconsistencies, trait-import friction, and feature-flag dead-ends with
+**compiler-verified evidence**. This is the authoritative "what would a new user trip
+over" pass.
+
+### C. Synthesize the report
+
+Merge both reviews into a single report. **Apply no change** — this mode is advisory.
+Produce:
+
+1. **Lingering inconsistencies** — a flat list of every inconsistency found, each with a
+   `file:line` (or API path) and a one-line description.
+2. **Recommended changes, split by impact:**
+   - **Breaking** — changes that alter the public API (renames, signature changes, removed
+     items, new required trait methods). For each: what to change, why it improves the
+     library, and the migration cost. Mark these "land now or wait for the next major" — a
+     major-version release is the only non-breaking window to make them.
+   - **Non-breaking** — additive or internal changes (new constructors, doc fixes, new
+     re-exports, deprecations that keep the old path working). For each: what to change and
+     why.
+3. **Recommendation** — is the library consistent enough to release as-is, or are there
+   high-impact items that should land in this version first? Be explicit about which
+   breaking items, if deferred, are stuck until the next major.
+
+After presenting the report, ask whether to address findings first or proceed to the
+version bump below.
+
+## Version bump
+
+These numbered steps are the default mode — run them when the argument is a version
+string, or after a release review once the user opts to proceed.
+
+### 1. Determine which crates to bump
+
+This repo has three crates:
+- `cached` — always bumped
+- `cached_proc_macro` — bump if this PR/branch touched `cached_proc_macro/`
+- `cached_proc_macro_types` — bump only if this PR/branch touched `cached_proc_macro_types/`
+
+Run the helper script to detect which crates need bumping:
+
+```bash
+.agents/skills/release/detect-crates.sh
+```
+
+This outputs one crate name per line based on `git diff origin/master`. When in doubt, bump `cached` and `cached_proc_macro` together (the common case); `cached_proc_macro_types` rarely changes.
+
+### 2. Update `Cargo.toml` versions
+
+Files to update (only for crates being bumped):
+
+**`Cargo.toml`** (the `cached` crate):
+- `[package] version` → new version
+- `[dependencies.cached_proc_macro] version` → new version (if bumping proc_macro)
+- `[dependencies.cached_proc_macro_types] version` → new version (if bumping proc_macro_types)
+
+**`cached_proc_macro/Cargo.toml`**:
+- `[package] version` → new version (if bumping proc_macro)
+
+**`cached_proc_macro_types/Cargo.toml`**:
+- `[package] version` → new version (if bumping proc_macro_types)
+
+Use precise string replacement — do not change dependency versions for third-party crates.
+
+### 3. Update `CHANGELOG.md`
+
+- Replace `## [Unreleased]` with `## [X.Y.Z / cached_proc_macro X.Y.Z]` (include only the crates being bumped in the heading — omit `cached_proc_macro_types` if it is not bumped)
+- Add a fresh `## [Unreleased]` section above the new version heading
+- The changelog must always have an `[Unreleased]` section at the top
+
+### 4. Create or update migration guide
+
+Every release requires a migration guide in `docs/migrations/` named `PREV-to-X.Y.Z.md`
+(e.g. `1.1-to-1.2.md`). If there are no breaking changes, the guide still must exist and
+must state there are no breaking changes.
+
+Migration guides are written for **agent consumption**: terse, mechanical, grep-friendly.
+Required sections:
+
+- **Versions** header line
+- **Breaking changes** — one subsection per change with Detection (what to grep/search for)
+  and Action (exact code transformation). If none, write "None. This release is purely additive."
+- **New APIs** — additive changes; note the feature gate if any
+- **Required Cargo.toml change** — exact before/after snippet
+- **VERIFY** — the `cargo build` / `cargo test` commands needed to confirm a successful migration,
+  plus any expected new compile errors and their fixes
+
+See existing guides in `docs/migrations/` for the established format.
+
+If the guide for this version already exists (e.g. was drafted ahead of the release), review it
+against the final diff and update any stale type names, method signatures, or behavior descriptions.
+
+### 5. Regenerate README
+
+```bash
+cargo readme --no-indent-headings > README.md
+```
+
+### 6. Verify
+
+```bash
+cargo check --no-default-features --features "proc_macro,time_stores"
+```
+
+Fix any compilation errors before proceeding.
+
+### 7. Commit or amend
+
+If there is already a single commit ahead of master on this branch, amend it:
+```bash
+git add Cargo.toml cached_proc_macro/Cargo.toml cached_proc_macro_types/Cargo.toml CHANGELOG.md README.md
+git commit --amend --no-edit
+```
+
+Otherwise create a new commit:
+```bash
+git commit -m "release: bump version to X.Y.Z"
+```
+
+Do not add a `Co-Authored-By` line.
+
+### 8. Report
+
+Tell the user:
+- Which crates were bumped and to what version
+- Whether `cached_proc_macro_types` was left unchanged and why
+- That README was regenerated
+- The resulting commit SHA

.agents/skills/release/detect-crates.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Detect which crates need version bumps based on files changed vs base ref.
+#
+# Usage: detect-crates.sh [BASE_REF]   (default: origin/master)
+#
+# Output: one line per crate to bump — "cached", "cached_proc_macro", "cached_proc_macro_types"
+# `cached` is always included.
+
+set -euo pipefail
+
+BASE=${1:-origin/master}
+
+changed=$(git diff "$BASE" --name-only)
+
+echo "cached"
+
+if echo "$changed" | grep -q "^cached_proc_macro/"; then
+    echo "cached_proc_macro"
+fi
+
+if echo "$changed" | grep -q "^cached_proc_macro_types/"; then
+    echo "cached_proc_macro_types"
+fi