@cyanheads/mcp-ts-core 0.12.7 → 0.12.8

package/skills/code-simplifier/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Post-session code review and cleanup against a working tree of changes. Analyzes `git diff` to simplify, consolidate, and align changed code with the existing codebase — modernize syntax, remove unnecessary complexity, consolidate duplicated logic, catch efficiency issues. Use after a substantive working session, or when asked to clean up, simplify, reduce slop, consolidate, modernize, tighten up, or de-slop code. For `@cyanheads/mcp-ts-core` projects, includes specific transformations for tool/resource/prompt definitions, the ctx pattern, error factories, and framework idioms.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: workflow
 ---
@@ -21,7 +21,7 @@ Post-session cleanup pass. Reviews what changed, understands how it fits the exi
 
 ### Phase 1: Identify changes
 
-Run `git status` to see the shape of the working tree, then `git diff HEAD` for all uncommitted changes (staged and unstaged). Untracked files never appear in the diff — read new files directly. If the tree is clean, review the most recently modified files from the current session.
+Run `git status` to see the shape of the working tree, then `git diff HEAD` for all uncommitted changes (staged and unstaged). Untracked files never appear in the diff — read new files directly. If the diff is empty and there are no untracked files, review the last commit (`git diff HEAD~1 HEAD`); if that is also empty, say the tree is clean and stop. Don't go hunting through the codebase for files to improve.
 
 ### Phase 2: Understand the surrounding codebase
 
@@ -29,7 +29,8 @@ Don't review changes in isolation. Before any modifications:
 
 1. **Read the full files** containing changes — not just the diff hunks. Understand imports, surrounding logic, module structure.
 2. **Identify the project language(s)** and select the relevant transformation rules. Discard inapplicable rules.
-3. **Survey adjacent code** — shared utilities, sibling modules, common patterns. You need to know what already exists before deciding something is missing. For mcp-ts-core projects, check `src/utils/` for project utilities, `src/errors/` for error handling, and `node_modules/@cyanheads/mcp-ts-core/` for framework exports.
+3. **Survey adjacent code** — shared utilities, sibling modules, common patterns. You need to know what already exists before deciding something is missing.
+4. **Run the project's gate once before editing** to establish a baseline. Find it in `package.json` scripts — `devcheck` if present, else `check`, else the separate `typecheck` / `lint` / `test` scripts; Python projects gate on `uv run ruff check`, `uv run ruff format --check`, and the configured type checker and test runner. In a Bun project that tests with Vitest, run `bun run test` — bare `bun test` bypasses the script and runs Bun's own runner. If the gate is already red, say so in the summary and don't attribute the failure to your changes.
 
 ### Phase 3: Review
 
@@ -37,29 +38,35 @@ Evaluate the changes across these dimensions. Not every dimension applies to eve
 
 #### Codebase cohesion
 
-- **Reuse** — Search for existing utilities, helpers, and patterns that could replace newly-written code. For mcp-ts-core projects, prefer `import from '@cyanheads/mcp-ts-core/utils'` over hand-rolled equivalents — pagination helpers, schema builders, retry primitives, and OTel attribute constants are framework-provided.
+- **Reuse** — Search for existing utilities, helpers, and patterns that could replace newly-written code. Check utility directories, shared modules, and files adjacent to the changed ones. If a function already exists that does what the new code does, use it.
 - **Consolidation** — Flag copy-paste-with-variation: near-duplicate code blocks that should be unified. Only unify if the shared abstraction is genuinely simpler than the duplicated code.
 - **Consistency** — Check that new code follows the same patterns as the rest of the codebase: naming conventions, error handling style, import patterns, type annotation style. Normalize toward the better variant when the project is inconsistent.
-- **Stringly-typed code** — Flag raw strings where constants, string-union types, branded types, or framework attribute constants already exist. For mcp-ts-core projects, the `ATTR_*` constants in `@cyanheads/mcp-ts-core/utils` should replace raw OTel attribute keys.
+- **Stringly-typed code** — Flag raw strings where constants, string-union types, or branded types already exist in the codebase.
 
 #### Code quality
 
 - **Redundant state** — State that duplicates existing state, cached values that could be derived.
 - **Unnecessary complexity** — Deep nesting that could be guard clauses, premature abstractions, over-engineered solutions to simple problems.
-- **Dead code** — Unreachable branches, unused variables, commented-out code, exports that nothing imports.
-- **Defensive code for impossible states** — Guards for cases the type system or framework already prevents. Drop them.
+- **Dead code** — Unreachable branches, unused variables, commented-out code. An export nothing imports is dead in an application or a package-internal module; on a published package's public surface it is API — leave it and note it in the summary.
+- **Defensive code for impossible states** — Guards for cases the type system or upstream validation already prevents. Drop them.
+- **Type escapes** — `any`, `as` casts that paper over a mismatch, non-null `!`, and `@ts-ignore`. Each is a claim the compiler couldn't check: replace with a narrowed type, a type guard, or a parse at the boundary. Keep the ones documenting a genuine type-system or third-party-types limitation, and prefer `@ts-expect-error` with a one-line reason over `@ts-ignore`.
+- **Swallowed errors** — Empty `catch {}`, `catch { return null }`, and `try` blocks that log and continue. A fallback that hides a failure is worse than the crash it prevents: rethrow or let it propagate. When wrapping, preserve the chain (`new Error(msg, { cause })`, `raise X from err`).
+- **Comment noise** — Strip comments that restate the code, commented-out code, and comments describing behavior the diff removed. Keep file headers, export JSDoc, and any comment carrying a *why* — a constraint, a workaround, an upstream bug reference.
 - **Outdated patterns** — Verbose or legacy syntax where modern equivalents exist. See the transformation tables below.
 
 #### Efficiency
 
 - **Redundant work** — Repeated computations, duplicate file reads, duplicate network/API calls, N+1 query patterns.
 - **Missed concurrency** — Independent async operations run sequentially that could run in parallel with `Promise.all` / `Promise.allSettled`.
+- **Unbounded fan-out** — `Promise.all` / `asyncio.gather` over a caller-sized or otherwise unbounded array fires everything at once. Cap it with the project's existing concurrency helper or a batched loop. A fixed handful of independent calls needs no limit.
 - **No-op updates** — State/store updates inside loops or event handlers that fire unconditionally. Add change-detection so downstream consumers aren't notified when nothing changed.
 - **TOCTOU** — Pre-checking file/resource existence before operating on it. Operate directly and handle the error instead.
 - **Overly broad operations** — Reading entire files when only a portion is needed, loading all items when filtering for one.
 
 #### mcp-ts-core-specific
 
+- **Gate** — `bun run devcheck` plus the test suite (`bun run test`) is the project gate in Phase 2 step 4 and Phase 4 step 5.
+- **Framework-provided utilities** — Before hand-rolling, check `src/utils/` and `src/errors/` in the project and `node_modules/@cyanheads/mcp-ts-core/` for framework exports: pagination helpers, schema builders, retry primitives, and the `ATTR_*` OTel attribute constants are framework-provided. Raw OTel attribute keys should be `ATTR_*` imports from `@cyanheads/mcp-ts-core/utils`.
 - **Error throwing patterns** — Prefer framework error factories (`McpError`, `validationError`, `notFound`, `httpErrorFromResponse`) over raw `throw new Error()`. Tool handlers should throw — the framework catches, classifies, and instruments.
 - **Error codes** — `InvalidParams` only for malformed JSON-RPC params shape. `ValidationError` for domain validation. `NotFound` for missing entities. Don't conflate them.
 - **Ctx usage** — Use `ctx.log`, `ctx.state`, `ctx.enrich` — don't reach for global loggers or request-scoped storage directly. The `ctx` pattern carries tenant scope and OTel context.
@@ -67,19 +74,24 @@ Evaluate the changes across these dimensions. Not every dimension applies to eve
 - **Tool annotations** — `readOnlyHint`, `idempotentHint`, `openWorldHint` should reflect reality. A read-only tool with `readOnlyHint: false` gives clients the wrong picture.
 - **`exactOptionalPropertyTypes` boundaries** — If a downstream type insists on the field being present-or-not-present (not present-as-undefined), use a mapped widening type at the boundary. The pattern is documented in the framework.
 - **`format()` ↔ `structuredContent` parity** — Different MCP clients forward different surfaces. Tests should assert both surfaces carry equivalent data.
+- **Defensive code** — the "impossible states" the framework already prevents include malformed params (Zod-validated before the handler runs) and unclassified errors (caught and classified after it throws). Guards for either are dead.
+- **Public surface** — the MCP surface (every tool input/output schema advertised to clients) is public API for the "API compatibility" rule; changing one is a breaking change, not a refactor.
 
 ### Phase 4: Apply transformations
 
 1. **Filter findings ruthlessly.** If a finding is a false positive or not worth the churn, skip it. Don't argue with yourself about borderline cases — move on.
-2. **Transform incrementally** — one category of change at a time (modernize syntax, then reduce nesting, then consolidate).
-3. **Verify equivalence** — all functionality, types, and public interfaces must remain unchanged. Run the project's gates after transforming (`bun run devcheck` and the test suite in mcp-ts-core projects; typecheck/lint/tests elsewhere); a simplification that breaks the build is worse than the verbosity it removed.
-4. **Keep the diff minimal.** Only touch lines that have a real reason to change. Don't reformat untouched code, add comments to code you didn't modify, or "improve" things that are already fine.
+2. **Stay in scope.** Edit only files in the diff or new this session. Touch a file outside that set only when a finding requires it — importing an existing helper, deleting a private export the diff just orphaned — and only on the lines that finding names. Anything broader goes in the summary as a recommendation, not into the tree.
+3. **Correctness bugs are not this pass's job.** A real defect doesn't get folded into a cleanup diff — name it in the summary with file and line so it can be handled as its own change.
+4. **Transform incrementally** — one category of change at a time (modernize syntax, then reduce nesting, then consolidate).
+5. **Verify equivalence** — all functionality, types, and public interfaces must remain unchanged. Re-run the gate from Phase 2 after transforming; a simplification that breaks the build is worse than the verbosity it removed.
+6. **Keep the diff minimal.** Only touch lines that have a real reason to change. Don't reformat untouched code, add comments to code you didn't modify, or "improve" things that are already fine. Formatting belongs to the formatter (Biome, ruff): never hand-adjust whitespace, quotes, or import order, and never let a formatting-only hunk into the diff.
+7. **Never stage, commit, tag, or push.** This pass ends with a dirty working tree and a summary; landing the changes is the caller's call.
 
-When done, briefly summarize what was fixed or confirm the code was already clean.
+When done, briefly summarize what was fixed, what was deliberately skipped, and any defects or out-of-scope recommendations — or confirm the code was already clean.
 
 ## Common transformations
 
-The tables below cover TypeScript and Python. For other languages, apply analogous principles: prefer modern idioms, reduce nesting, eliminate dead code, follow project conventions.
+The tables below cover TypeScript and Python. For other languages, apply analogous principles: prefer modern idioms, reduce nesting, eliminate dead code, follow project conventions. Check the project's language floor (`tsconfig` target/lib, `pyproject` `requires-python`) before applying a version-gated row.
 
 ### TypeScript (modern ESM, TS 5.x+)
 
@@ -90,11 +102,17 @@ The tables below cover TypeScript and Python. For other languages, apply analogo
 | `if (x !== null && x !== undefined)` | `if (x != null)` | Idiomatic null/undefined check |
 | `arr.filter(x => x !== null) as T[]` | `arr.filter(x => x != null)` | TS 5.5+ infers the type predicate — no cast; on older TS use an explicit `(x): x is T` predicate |
 | `export { foo } from './foo/index.js'` | Direct imports at call sites | Avoid barrel re-exports inside the package; barrel exports are for public APIs only |
+| `import { readFile } from 'fs/promises'` | `import { readFile } from 'node:fs/promises'` | `node:` protocol — unambiguous, lint-enforced in Biome |
 | `async function f() { const a = await x(); const b = await y(); }` | `const [a, b] = await Promise.all([x(), y()])` | Parallel when independent |
-| `obj.x !== undefined ? obj.x : fallback` | `obj.x ?? fallback` | Nullish coalescing |
+| `value \|\| fallback` | `value ?? fallback` | `\|\|` also swallows `0`, `''`, and `false` — use `??` unless every falsy value really should take the fallback |
+| `obj.x !== undefined ? obj.x : fallback` | `obj.x ?? fallback` | Nullish coalescing — equivalent only when `null` should take the fallback too |
 | `if (a) { if (b) { if (c) { ... } } }` | Guard clauses with early returns | Reduce nesting |
-| `try { risky() } catch (e: any) { ... }` | `try { risky() } catch (e: unknown) { ... }` | Type-safe error handling |
-| `enum Status { A, B, C }` | `const Status = { A: 'A', B: 'B', C: 'C' } as const` | Prefer const objects over enums — but switching numeric values to strings changes serialized output; keep values stable if they're persisted (string enums are acceptable) |
+| `try { risky() } catch (e: any) { ... }` | `try { risky() } catch (e) { ... }` | Under `strict` the catch binding is already `unknown`; narrow with a type guard before use |
+| `catch (err) { throw new Error('load failed') }` | `throw new Error('load failed', { cause: err })` | Preserve the cause chain |
+| `[...arr].sort(cmp)` / `arr.slice().sort(cmp)` | `arr.toSorted(cmp)` | Non-mutating array methods (ES2023) — also `toReversed`, `toSpliced`, `with` |
+| `const c = new AbortController(); setTimeout(() => c.abort(), ms)` | `AbortSignal.timeout(ms)` | Built-in timeout signal; combine with a caller's signal via `AbortSignal.any([...])` |
+| `JSON.parse(JSON.stringify(x))` | `structuredClone(x)` | Deep clone that preserves Date, Map, Set, and cycles |
+| `enum Status { A, B, C }` | `const Status = { A: 'A', B: 'B', C: 'C' } as const` | `enum`, `namespace`, and constructor parameter properties are non-erasable syntax rejected by TS 5.8 `erasableSyntaxOnly` and Node type-stripping — but switching numeric values to strings changes serialized output; keep values stable if they're persisted |
 | `function f(a: string, b: string, c: string, d?: string)` | `function f(opts: FnOptions)` | Options object when >3 params |
 | `throw new Error('Bad input')` (in a tool handler) | `throw validationError('Bad input', { field: 'x' })` | Use framework error factories so the framework can classify and instrument |
 | `const ATTR_KEY = 'mcp.tool.name'` | `import { ATTR_MCP_TOOL_NAME } from '@cyanheads/mcp-ts-core/utils'` | Use framework attribute constants |
@@ -105,16 +123,20 @@ The tables below cover TypeScript and Python. For other languages, apply analogo
 | --- | --- | --- |
 | `Optional[str]` | `str \| None` | Modern union syntax (3.10+) |
 | `List[str]`, `Dict[str, int]` | `list[str]`, `dict[str, int]` | Built-in generics (3.9+) |
-| `if x == 0: ... elif x == 1: ... elif x == 2: ...` | `match x: case 0: ... case 1: ...` | Structural pattern matching (3.10+) |
-| `class Config: def __init__(self, a, b, c): self.a = a ...` | `@dataclass class Config: a: str; b: int; c: float` | Less boilerplate, built-in eq/repr |
+| `T = TypeVar("T")` + `def f(x: T) -> T` | `def f[T](x: T) -> T` | PEP 695 generics (3.12+) — also `class C[T]:` |
+| `TypeAlias = Union[A, B, C]` | `type ABC = A \| B \| C` | `type` statement (3.12+) |
+| `if isinstance(x, Foo): a = x.a; b = x.b` | `match x: case Foo(a=a, b=b): ...` | Structural pattern matching (3.10+) where it destructures — not as a replacement for a flat equality `if/elif` chain |
+| `class Config: def __init__(self, a, b, c): self.a = a ...` | `@dataclass(slots=True) class Config: a: str; b: int; c: float` | Less boilerplate, built-in eq/repr; `frozen=True` when instances shouldn't mutate |
 | `results = []; for item in items: results.append(transform(item))` | `results = [transform(item) for item in items]` | Idiomatic comprehension |
 | `f = open('x'); try: ... finally: f.close()` | `with open('x') as f: ...` | Context manager for resources |
+| `os.path.join(d, n)`, `os.path.exists(p)`, `open(p).read()` | `Path(d) / n`, `p.exists()`, `p.read_text()` | `pathlib` over `os.path` string juggling |
+| `datetime.utcnow()` / `datetime.utcfromtimestamp(t)` | `datetime.now(UTC)` / `datetime.fromtimestamp(t, UTC)` | Deprecated in 3.12 — the old calls return naive datetimes that compare wrong against aware ones |
+| `zip(a, b)` | `zip(a, b, strict=True)` | 3.10+ — silently truncating to the shorter input hides bugs |
 | `m = pattern.match(s)` then `if m: use(m)` | `if (m := pattern.match(s)): use(m)` | Walrus operator where it removes a throwaway assignment |
 | `"Hello " + name + "!"` | `f"Hello {name}!"` | f-string over concatenation |
 | `except Exception as e: pass` | `except SpecificError as e: log(e)` | Catch specific, never bare except/pass |
 | `from module import *` | `from module import specific_name` | Explicit imports only |
-| `TypeAlias = Union[A, B, C]` | `type ABC = A \| B \| C` | `type` statement (3.12+) |
-| Sequential `await` for independent I/O | `await asyncio.gather(a(), b())` | Parallel when independent |
+| Sequential `await` for independent I/O | `async with asyncio.TaskGroup() as tg: tg.create_task(a()); tg.create_task(b())` | Structured concurrency (3.11+) — cancels siblings on failure and raises an `ExceptionGroup`; `asyncio.gather(..., return_exceptions=True)` stays correct when every result is wanted regardless of failures |
 
 ## When NOT to simplify
 
@@ -124,7 +146,12 @@ Leave code alone when:
 - **The change is cosmetic.** Renaming a variable from `data` to `result` isn't worth the churn.
 - **Intentional verbosity for debugging.** Verbose code may exist to make stack traces or logging clearer.
 - **Performance-critical paths.** A less readable version may exist for measured performance reasons — check before simplifying.
-- **API compatibility.** Don't change public function signatures, export shapes, or return types that callers depend on. For mcp-ts-core projects, the public surface includes tool input/output schemas exposed via MCP — changing them is a breaking change to the server's MCP surface.
+- **API compatibility.** Don't change public function signatures, export shapes, or return types that callers depend on.
 - **Tests.** Don't DRY up test code aggressively — test readability and isolation matter more than deduplication.
 - **Type workarounds.** Sometimes an `as` cast or `# type: ignore` exists because of a genuine type system limitation — verify before removing.
 - **The abstraction isn't proven.** Don't create a shared utility for two similar blocks of code. Wait until there are three, and even then only if the abstraction is genuinely simpler than the duplication.
+- **`return await` inside `try` / `finally`.** Collapsing it to `return` is not equivalent — the promise settles outside the block, so `catch` never fires and `finally` runs early. Only strip `await` from a `return` in plain function-body position.
+- **Lazy logging arguments.** `logger.info("loaded %s in %sms", name, ms)` defers formatting until the record is emitted — don't turn it into an f-string.
+- **Awaits that only look independent.** Sequential I/O may be sequential on purpose: rate limits, upstream ordering, a write that must land before the next read. Confirm independence from the code, not from the shape of the calls, before reaching for `Promise.all`.
+- **Generated and vendored files.** Lockfiles, generated clients and schemas, migrations, snapshots, and anything under `dist/` are regenerated, not edited — skip them even when they appear in the diff.
+- **Tool descriptions and `.describe()` prose.** They are the contract an LLM client reads — tightening them for brevity degrades the surface. Treat them as API text, not as comments.

package/skills/field-test/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: field-test
 description: >
-  Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
+  Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, measures every call (bytes, token estimate, wall-clock) and weighs the catalog, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.10"
+  version: "2.12"
   audience: external
   type: debug
 ---
@@ -45,7 +45,8 @@ cat > /tmp/<project-name>-field-test-9DJ73-K103L.sh <<'HELPER_EOF'
 #
 # Surfaces failures aggressively — field test is for finding things that fail,
 # so the helper auto-tails logs and prints HTTP status/body on errors instead
-# of swallowing them.
+# of swallowing them. It also measures: every mcp_call prints a one-line
+# size/latency reading on stderr, and mcp_catalog_size weighs tools/list.
 
 # Usage: mcp_start /path/to/server [startup-timeout-seconds]   (default: 30)
 # Builds, starts the HTTP server in the background, waits for the listen line,
@@ -107,7 +108,10 @@ _mcp_init_fail() {
 
 # Usage: mcp_init <url>
 # Runs `initialize`, sends `notifications/initialized`, prints:
-#   ready sid=<id-or-empty> protocol=<negotiated-version> requested=<want> (HTTP <code>)
+#   ready sid=<id-or-empty> protocol=<negotiated-version> requested=<want> instructions=<bytes>B (HTTP <code>)
+# `instructions=` is the byte size of the server's `instructions` string — it
+# loads into every client session alongside tools/list, so it is the other half
+# of the per-session context tax mcp_catalog_size weighs.
 # The initialize *result* is what decides success — a session ID is optional.
 # A server started with MCP_SESSION_MODE=stateless mints none, and the session
 # header is then omitted from every later request. Capture BOTH `sid` and
@@ -151,13 +155,44 @@ mcp_init() {
     _mcp_init_fail "initialize result declares no protocolVersion" "$body_file" "$hdr"
     return 1
   fi
+  local instr; instr=$(printf '%s' "$reply" | jq -r '.result.instructions // "" | utf8bytelength' 2>/dev/null || echo 0)
   local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
   local init_headers=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "MCP-Protocol-Version: $got")
   [ -n "$sid" ] && init_headers+=(-H "Mcp-Session-Id: $sid")
   curl -sS -X POST "$url" "${init_headers[@]}" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
   rm -f "$hdr" "$body_file"
-  echo "ready sid=$sid protocol=$got requested=$want (HTTP $code)"
+  echo "ready sid=$sid protocol=$got requested=$want instructions=${instr}B (HTTP $code)"
+}
+
+# Internal: one stderr line per call — reply bytes, the content/structured
+# split, a token estimate, wall-clock. Bytes are the reply as delivered (SSE
+# framing stripped). `content` is every text block's bytes, `structured` is
+# structuredContent serialized. The token figure is bytes/4 — an estimate, not
+# a tokenizer. Wall-clock is curl's time_total for the whole exchange.
+_mcp_measure() {
+  local method="$1"; local params="$2"; local reply="$3"; local code="$4"; local secs="$5"
+  local total; total=$(printf '%s' "$reply" | wc -c | tr -d ' ')
+  local ms; ms=$(awk -v s="$secs" 'BEGIN { printf "%d", s * 1000 }')
+  local label="$method"
+  local split=""
+  case "$method" in
+    tools/call)
+      local name; name=$(printf '%s' "$params" | jq -r '.name // empty' 2>/dev/null)
+      [ -n "$name" ] && label="$method $name"
+      split=$(printf '%s' "$reply" | jq -r '
+        (.result // {}) as $r
+        | ([$r.content[]? | select(.type == "text") | .text] | join("") | utf8bytelength) as $c
+        | (if $r.structuredContent == null then "none" else ($r.structuredContent | tojson | utf8bytelength | tostring) end) as $s
+        | "content \($c) · structured \($s)"' 2>/dev/null)
+      ;;
+    resources/read)
+      split=$(printf '%s' "$reply" | jq -r '
+        "text \([.result.contents[]? | .text // ""] | join("") | utf8bytelength)"' 2>/dev/null)
+      ;;
+  esac
+  local tok; tok=$(awk -v b="$total" 'BEGIN { if (b >= 1000) printf "~%.1fk", b / 4000; else printf "~%d", b / 4 }')
+  echo "⏱ $label · HTTP $code · ${total} B${split:+ ($split)} · $tok tok · ${ms} ms" >&2
 }
 
 # Usage: mcp_call <url> <sid> <method> [JSON_PARAMS] [protocol]
@@ -166,6 +201,9 @@ mcp_init() {
 # emitting every event would break `| jq .result`). A transport failure or an
 # HTTP >= 400 prints the details and returns non-zero — it never returns 0 with
 # empty output. Pipe to `jq`.
+# Every call also prints one measurement line on stderr, e.g.
+#   ⏱ tools/call gbif_search_species · HTTP 200 · 18412 B (content 9100 · structured 8900) · ~4.6k tok · 812 ms
+# Read it on every call — it is the size/latency evidence the report cites.
 # `sid` may be empty ('') for a stateless server; the session header is then
 # omitted. Pass the `protocol` mcp_init printed as the 5th arg — with no
 # session carrying the negotiation, MCP-Protocol-Version is what tells the
@@ -180,12 +218,13 @@ mcp_call() {
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s","params":%s}' "$RANDOM" "$method" "$params")
   fi
   local resp_file; resp_file=$(mktemp)
-  local code curl_rc
+  local stats code secs curl_rc
   local headers=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")
   [ -n "$sid" ] && headers+=(-H "Mcp-Session-Id: $sid")
   [ -n "$protocol" ] && headers+=(-H "MCP-Protocol-Version: $protocol")
-  code=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$url" "${headers[@]}" -d "$body")
+  stats=$(curl -sS -o "$resp_file" -w '%{http_code} %{time_total}' -X POST "$url" "${headers[@]}" -d "$body")
   curl_rc=$?
+  read -r code secs <<< "$stats"
   if [ "$curl_rc" -ne 0 ] || [ -z "$code" ] || [ "$code" = "000" ]; then
     echo "TRANSPORT FAILURE calling $method — curl exit $curl_rc, http_code '${code:-none}'." >&2
     echo "Server not reachable at $url (check it is still running: mcp_log <log>)." >&2
@@ -198,14 +237,44 @@ mcp_call() {
     rm -f "$resp_file"
     return 1
   fi
+  local reply
   local sse; sse=$(sed -n 's/^data: //p' "$resp_file")
   if [ -n "$sse" ]; then
-    local reply; reply=$(printf '%s\n' "$sse" | grep -E '"(result|error)"')
-    printf '%s\n' "${reply:-$sse}"
+    reply=$(printf '%s\n' "$sse" | grep -E '"(result|error)"')
+    reply="${reply:-$sse}"
   else
-    cat "$resp_file"
+    reply=$(cat "$resp_file")
   fi
   rm -f "$resp_file"
+  _mcp_measure "$method" "$params" "$reply" "$code" "$secs"
+  printf '%s\n' "$reply"
+}
+
+# Usage: mcp_catalog_size <url> <sid> [protocol]
+# Weighs the catalog: the bytes of the tools/list reply — what every client
+# loads into context per session before a single call — then each tool's
+# serialized entry, largest first, split into description / inputSchema /
+# outputSchema so the row says WHERE the weight is. A fat outputSchema costs as
+# much as a fat description and is the usual surprise. Prints:
+#   catalog: 12 tools · 48210 B · ~12.1k tok
+#   <bytes>  <~tok>  <name>  desc <b> · input <b> · output <b|none>   (one row per tool)
+mcp_catalog_size() {
+  local url="$1"; local sid="$2"; local protocol="${3:-}"
+  [ -z "$url" ] && { echo "usage: mcp_catalog_size <url> <sid> [protocol]" >&2; return 1; }
+  local reply; reply=$(mcp_call "$url" "$sid" tools/list '' "$protocol") || return 1
+  printf '%s' "$reply" | jq -r '
+    def tok: if . >= 1000 then "~\(. / 4000 * 10 | round / 10)k" else "~\(. / 4 | floor)" end;
+    def bytes_or_none: if . == null then "none" else (tojson | utf8bytelength | tostring) end;
+    (.result.tools // []) as $t
+    | (. | tojson | utf8bytelength) as $total
+    | "catalog: \($t | length) tools · \($total) B · \($total | tok) tok",
+      ($t
+       | map({name, b: (tojson | utf8bytelength),
+              d: ((.description // "") | utf8bytelength),
+              i: (.inputSchema | bytes_or_none),
+              o: (.outputSchema | bytes_or_none)})
+       | sort_by(-.b) | .[]
+       | "\(.b)\t\(.b | tok)\t\(.name)\tdesc \(.d) · input \(.i) · output \(.o)")'
 }
 
 # Usage: mcp_log <server-log-path> [N]   (default: 50 lines)
@@ -273,7 +342,7 @@ Capture `pid`, `url`, `port`, `log` from the `mcp_start` output — every later
 mcp_init <url-from-mcp_start>
 ```
 
-Runs `initialize`, sends `notifications/initialized`, prints the `sid` and `protocol` to capture for `mcp_call`. Success is decided by the initialize *result*, so a transport failure, a non-2xx status, a JSON-RPC error, a malformed body, or a result with no `protocolVersion` all fail loudly with the raw exchange.
+Runs `initialize`, sends `notifications/initialized`, prints the `sid` and `protocol` to capture for `mcp_call`, plus `instructions=` — the byte size of the server's `instructions` string, which every client loads per session alongside the catalog (record it with the catalog total in Step 3). Success is decided by the initialize *result*, so a transport failure, a non-2xx status, a JSON-RPC error, a malformed body, or a result with no `protocolVersion` all fail loudly with the raw exchange.
 
 The helper requests the newest `initialize`-negotiated revision the SDK supports (`2025-11-25`). **If `protocol=` comes back older than `requested=`, the server capped it** — every call after that exercises an older protocol than a current client would negotiate. Note it as a `bug` finding and check the pinned `@modelcontextprotocol/server` version; don't quietly test the downgraded surface. To deliberately test an older version, set `MCP_FIELD_TEST_PROTOCOL`.
 
@@ -294,8 +363,11 @@ Both modes exercise the **2025-era arm**: `initialize` negotiates the revision,
 mcp_call <url> <sid> tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema}'
 mcp_call <url> <sid> resources/list | jq '.result.resources[] | {uri, name, mimeType}'
 mcp_call <url> <sid> prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
+mcp_catalog_size <url> <sid> <protocol>
 ```
 
+**Weigh the catalog.** `mcp_catalog_size` prints the `tools/list` bytes — the context every client loads per session before a single call — and each tool's entry, largest first, split into description / `inputSchema` / `outputSchema`. Record the total alongside the `instructions=` bytes from Step 2; together they are the per-session tax. The split says where a heavy tool's weight lives: an `outputSchema` narrating every field of a 60-field record is the common surprise, an over-long description the obvious one. Hand the outliers to `tool-defs-analysis` (its length-outliers pass) rather than trimming blind.
+
 Present a compact catalog to the user: each definition's name + 1-line description. Flag vague or missing descriptions as you go — those feed into the report. Use this to build the test plan.
 
 **Audit every description for leaks** — tool description, every parameter `.describe()` in `inputSchema`, and every field `.describe()` in `outputSchema` (the `outputSchema` projection above is what surfaces these; don't skim past it). Three categories:
@@ -317,6 +389,7 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 | Happy path | One realistic input. Output shape matches schema. `content[]` text reads clearly to a human. |
 | `structuredContent` ↔ `content[]` parity | Dump the whole array (`jq '.result.content'`) and check every `structuredContent` field is surfaced *somewhere* in it — enrichment lands in its own trailing block, not in `content[0]`. Parity gap = client-specific blindness. |
 | Input error | One invalid input (wrong type or missing required). Error text says *what*, *why*, *how to fix*. |
+| Size & latency | Read the `⏱` line `mcp_call` prints on every call. A happy-path response over **24,000 B** (the framework's `DEFAULT_OUTLINE_BUDGET_BYTES` — the line at which it would outline a document itself) with no truncation disclosure and no retrieval path (cursor, offset, `sections`, canvas handle) is a `ux` finding: the agent pays the whole payload with no way to ask for less. `content` ≈ `structured` with the text starting `{` means the JSON is on the wire twice — a missing `format()`. A call over ~5 s on a happy-path input is worth a `mcp_log` look before calling it upstream latency. |
 
 **Situational — add only when triggered**
 
@@ -349,7 +422,7 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 
 Use `TaskCreate` — one task per definition. Mark complete as you go. Don't batch.
 
-For each call, capture: input sent, response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
+For each call, capture: input sent, the `⏱` line (bytes, split, ms), response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
 
 When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/<project-name>-field-test-<ID>.sh && mcp_log <log>` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in the per-server log (read via `mcp_log`) rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone.
 
@@ -374,12 +447,16 @@ Kills the background server and its port-holding child, removes the server log,
 
 ### 7. Report
 
-Three sections. Tight. The user should be able to skim the summary, read details only for what matters, and act on numbered options.
+Four sections. Tight. The user should be able to skim the summary, scan the numbers, read details only for what matters, and act on numbered options.
 
 #### Summary (1 paragraph)
 
 One paragraph. How many definitions exercised, how many passed clean, how many have issues, and the single most important finding. No tables, no lists.
 
+#### Size & latency
+
+Per-session tax on its own line (`instructions` bytes + catalog bytes, with the heaviest tool named), then one row per tool exercised, sorted by happy-path bytes descending: tool · bytes · ~tok · ms. Over 15 tools, keep every row over 24,000 B plus the three slowest and fold the rest into one line ("N more under budget, median X B"). Numbers only — what they mean goes in Findings.
+
 #### Findings
 
 Only include definitions with issues. Group by severity. Each finding is 2–4 lines unless it genuinely needs more. A parity finding cites the full `content[]` dump as its evidence — a quote from one index doesn't establish drift.
@@ -421,6 +498,8 @@ End with:
 - [ ] HTTP server built and started; real port parsed from log
 - [ ] Session initialized (a stateless server returns an empty `sid` — still a pass); `notifications/initialized` sent; negotiated protocol version matches the requested one (a downgrade is a finding)
 - [ ] Catalog surfaced and presented; descriptions audited for leaks (implementation details, meta-coaching, consumer-aware phrasing)
+- [ ] Catalog weighed (`mcp_catalog_size`); total + `instructions=` bytes recorded for the report
+- [ ] Every call's `⏱` line read; any happy-path response over 24,000 B with no disclosure + retrieval path filed as `ux`
 - [ ] Universal battery run on every definition (happy path, parity against the full `content[]` array, input error)
 - [ ] Situational categories applied only when triggered
 - [ ] **If >15 tools:** sampled 30–40% for situational testing; skipped definitions listed in report
@@ -429,4 +508,4 @@ End with:
 - [ ] **If any tool truncates, caps, or spills its output:** truncation forced; disclosure + a retrieval path (cursor, offset, selector, canvas handle) verified
 - [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
 - [ ] Server stopped (port confirmed free); server log and helper script removed
-- [ ] Report: summary paragraph → grouped findings → numbered options
+- [ ] Report: summary paragraph → size & latency table → grouped findings → numbered options

package/skills/git-wrapup/SKILL.md

@@ -1,23 +1,35 @@
 ---
 name: git-wrapup
 description: >
-  Land working-tree changes as logical commits — the work grouped by concern, topped by a release commit (version bump, changelog, regenerated artifacts) and an annotated tag. Verify, commit, tag. Stops at "committed and tagged locally" — no push, no publish. The release-and-publish skill picks up from here. Distilled from the git_wrapup_instructions protocol.
+  Land working-tree changes as logical commits — the work grouped by concern, topped by a release commit (version bump, changelog, regenerated artifacts). Verify, commit. Stops at "committed locally on main" — or, when the project releases through a release PR, at "release branch pushed, PR open". No tag, no push to main, no publish: the release-and-publish skill merges, tags, and ships from here. Distilled from the git_wrapup_instructions protocol.
 metadata:
   author: cyanheads
-  version: "1.12"
+  version: "1.13"
   audience: external
   type: workflow
 ---
 
 ## When to use
 
-Working-tree or staged changes are ready to ship as a new version. This skill lands them as a stack of logical commits — the work grouped by concern, topped by a release commit (version + changelog + tree) — with an annotated tag. It does NOT push or publish — that's a separate step (`release-and-publish`).
+Working-tree or staged changes are ready to ship as a new version. This skill lands them as a stack of logical commits — the work grouped by concern, topped by a release commit (version + changelog + tree). It does NOT tag, push to main, or publish — `release-and-publish` does all three.
 
 Common triggers:
 - Feature work, bug fixes, or dependency updates are done and tested
 - A maintenance or polish pass left changes in the working tree
 - An orchestrator says "wrapup this project"
 
+## Release PR mode
+
+A project can route every release through a pull request — one PR per version, for the audit trail and a stable review target. The mode is declared in the project's `CLAUDE.md`/`AGENTS.md` or in the caller's brief; when neither says anything, there is no release PR and the stack lands on `main` directly.
+
+| Mode | Wrapup ends at | Then |
+|:--|:--|:--|
+| *(none — default)* | commit stack on `main`, tree clean | `release-and-publish` tags HEAD and ships |
+| **gated** | commit stack on `release/<version>`, branch pushed, PR open | a review pass on the PR (`release-pr-review` skill), then a separate `release-and-publish` run fast-forwards `main`, tags, and ships |
+| **straight-through** | same as gated | the same agent continues straight into `release-and-publish` |
+
+The branch is created at wrapup time, never before: work happens on `main` until the version is known, then the uncommitted tree moves to `release/<version>` in one step (step 7). The commit stack, the release commit, and the tag format are identical in every mode — the PR adds an artifact around them, it does not change them.
+
 ## Pre-wrapup gate checklist
 
 Every item must be true before starting wrapup. Committing means releasing — a commit only happens when the work is ready to ship, not just "the edits are done." Each item is a goal to verify.
@@ -127,6 +139,15 @@ bun run test:package       # only if the script exists — NOT part of test:all
 
 ### 7. Commit — group by concern, release artifacts on top
 
+**Release PR mode only — move to the release branch first, before the first commit:**
+
+```bash
+git branch --show-current                 # must be main
+git switch -c release/<version>           # uncommitted work rides along
+```
+
+Commits never land on `main` in this mode. If a `release/*` branch already exists locally, a prior release PR was never merged — halt and report it rather than stacking a second release on top.
+
 Do NOT `git add -A` into one commit. Group the working tree into a handful of logical commits — never one blob:
 
 1. **The work — one commit per concern.** A feature spanning multiple layers splits by layer: runtime/logic, linter/tooling, docs/skills. Unrelated changes (two separate fixes, an incidental doc tweak) are their own commits. Work commits do not carry the version.
@@ -172,59 +193,74 @@ The changelog carries the depth, the tag carries the headline, the commit carrie
 
 **Right-size it.** "Group by concern" is not "always split." A genuinely single-concern change — one fix, a dependency bump, a small doc edit — is one work commit plus the release commit; when the change and its version bump are inseparable for a tiny patch, a single commit whose subject leads with the version is fine. The failure mode to prevent is the inverse: a large, multi-layer feature crammed into one commit alongside the release artifacts.
 
-### 8. Create an annotated tag
+### 8. Open the release PR (release PR mode only)
+
+Skip this step entirely when the project has no release PR mode — go to step 9.
 
 ```bash
-git tag -a v<version> --cleanup=whitespace -m "<tag message with embedded newlines>"
+git push -u origin release/<version>
+gh pr create --base main --head release/<version> --title "<release commit subject>" --body-file <path-to-body.md>
 ```
 
-Use `-m` with embedded newlines in the string (the commit `-m`-only constraint applies here too — no heredoc). The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
+**Title:** the release commit's subject, verbatim — `chore(release): <version> — <theme>`.
 
-`--cleanup=whitespace` is load-bearing. The default cleanup (`strip`) deletes `#`-leading lines as comments, so markdown headers silently vanish from the tag body. `--cleanup=verbatim` is worse: it skips end-of-message normalization, so with tag signing enabled the signature is appended flush against the message's last character — git then can't parse its own signature (the tag reads as unsigned) and the whole `-----BEGIN SSH SIGNATURE-----` block publishes verbatim into the GitHub Release body.
+**Body — always via `--body-file`, never an inline `--body` string** (backticks inside a double-quoted argument are command substitution and silently vanish). Write the file to a scratch location, not into the repo.
 
-Format — a **headline digest**, never a section-by-section changelog mirror:
+The body is the release digest — the same headline digest the annotated tag will carry, plus a gates record. It is written here, reviewed on the PR, and copied into the tag at release time, so it is the one place the release notes get reviewed before they become permanent. Format:
 
 ```
-<theme — omit version number, GitHub prepends v<VERSION>:>
+<theme — the changelog entry's summary: line, plain prose, one line>
+
+## Changes
 
 - <notable user-facing change> (#N)
 - <notable user-facing change> (#N)
 - <ONE compact grouped line for the minor/internal changes — build config, repo hygiene, metadata>
 - deps: `@cyanheads/mcp-ts-core` ^0.10.6 → ^0.10.14 (+ dev-dep bumps)
 
+## Gates
+
+- `bun run devcheck` — clean
+- `bun run rebuild` — ok
+- `bun run test:all` — <N> passed
+- `bun run test:package` — <N> passed   (only where the project defines it)
+
 [CHANGELOG v<version>](https://github.com/<OWNER>/<REPO>/blob/main/changelog/<major.minor>.x/<version>.md)
 ```
 
 **Rules:**
-- Subject line omits the version number (GitHub prepends `v<VERSION>:` to the release title)
-- **Flat bullets only — never Keep-a-Changelog section headers.** `Added:`/`Changed:`/`Fixed:`/`Dependency bumps:` belong in the changelog file; a tag that mirrors the changelog's structure is wrong even when every line is accurate
-- **Complete at headline granularity** — every changelog-worthy change stays visible: notable changes get their own bullet, minor/internal items (build config, repo hygiene, metadata) share ONE grouped compact bullet. Nothing silently dropped, nothing expanded — the changelog carries the depth, the tag carries the existence
-- **Deps: one line max**, naming only what earns it (the framework bump, a major); per-package arrows for the rest live in the changelog entry only
-- **No gates line** — test counts and devcheck status are changelog detail, not release-body material
-- No narrative preamble — bullets under the subject, no paragraph blocks
-- No marketing adjectives
-- Length is earned — a subject + two bullets + changelog link is a fine tag for a small patch
-- **Issue backlinks:** when changes address GitHub issues, include `(#N)` references in the relevant bullets — same as the changelog entry. The backlinks render as clickable links in the GitHub Release body.
-- **Changelog link (final line):** end the tag body with a Markdown link to this version's changelog file, so the GitHub Release offers a one-click jump to the full entry — `[CHANGELOG v<version>](https://github.com/<OWNER>/<REPO>/blob/main/changelog/<major.minor>.x/<version>.md)`. Derive `<OWNER>/<REPO>` from the origin remote; the path mirrors the file authored in step 4 (e.g. `changelog/0.10.x/0.10.12.md`). Keep the blank line above it so it renders as its own paragraph, not appended to the gates line.
+- **`## Changes` follows the tag rules exactly** (`release-and-publish` step 4): flat bullets, never Keep-a-Changelog section headers; complete at headline granularity — notable changes get their own bullet, minor/internal items share ONE grouped bullet; deps one line max, naming only what earns it; no narrative, no marketing adjectives. Depth lives in the changelog entry, which is in this PR's diff and linked on the last line.
+- **Every claim traces to the diff and to the changelog entry.** The body is derived from the entry you authored in step 4, never written independently of it.
+- **`## Gates` is the one release surface that carries gate results** — the exact commands from step 6 with their outcomes. It never enters the tag.
+- **Issue references are bare `(#N)` backlinks — never a closing keyword** (`Closes #N`, `Fixes #N`); the merge would close the issue before its close-out comment lands.
+- **Changelog link is the final line**, same form as the tag, blank line above it.
+- Length is earned — a theme, two bullets, gates, and the link is a complete body for a small patch.
+
+If the review pass changes what ships, `release-pr-review` updates `## Changes` and `## Gates` to match; `release-and-publish` then lifts `## Changes` plus the final link into the tag verbatim.
+
+**Gated mode: halt here.** Report the PR URL, the branch, and the commit stack. Do not tag, do not merge, do not touch `main`. The review pass and `release-and-publish` run as separate steps after this one.
+
+**Straight-through mode:** continue directly into `release-and-publish`.
 
 ### 9. Verify end state
 
 ```bash
 git log --oneline -8              # confirm the commit stack: work commits + release commit on top
-git show v<version> --stat | head -20   # confirm tag points at HEAD (the release commit)
 git status                        # must be clean
-git tag -l v<version> --format='%(if)%(contents:signature)%(then)signed%(else)unsigned%(end)'   # with tag signing enabled, must print "signed"
+git tag --points-at HEAD          # must print nothing — tagging is release-and-publish's job
+git branch --show-current         # main, or release/<version> in release PR mode
+gh pr view --json number,url,state   # release PR mode: OPEN, head = the branch above
 ```
 
-If the working tree isn't clean or the tag doesn't point at HEAD, something went wrong — investigate before proceeding. `unsigned` under enabled tag signing means the signature didn't parse (see step 8's cleanup note) — delete and recreate the tag before it leaks the signature block into the GitHub Release body.
+If the working tree isn't clean or the release commit isn't at HEAD, something went wrong — investigate before proceeding.
 
-**Do NOT push.** This skill stops here. Use the `release-and-publish` skill for the push + publish workflow.
+**Do NOT tag, push `main`, or publish.** This skill stops here. `release-and-publish` merges the release branch when there is one, creates the tag, pushes, and publishes.
 
 ## Constraints
 
-- **Local only.** No `git push`, no remote operations
+- **No push to `main`, no tag, no publish.** The only remote writes this skill makes are the release-branch push and the PR create in release PR mode
 - **Never stash.** Not for quick checks, not for testing, not for any reason
-- **Never destructive.** No `git reset --hard`, `git restore .`, `git clean -f`, `git checkout -- .`
+- **Never destructive.** No `git reset --hard`, `git restore .`, `git clean -f`, `git checkout -- .`, no force-push
 - **Bash git only.** Drive every git operation through the shell
 - If `v<version>` already exists as a tag, **halt and report the conflict** — include the version string, existing tag SHA, and current HEAD SHA so the caller can resolve it. Do not delete or move tags without explicit authorization
 
@@ -240,8 +276,9 @@ If the working tree isn't clean or the tag doesn't point at HEAD, something went
 - [ ] `bun run devcheck` passes
 - [ ] `bun run test:all` (or `test`) passes
 - [ ] `bun run test:package` passes, when the project defines it — it guards the public-export manifest and `test:all` does not run it
+- [ ] Release PR mode: stack committed on `release/<version>`, never on `main`
 - [ ] Work grouped into logical commits (large features split by layer); release artifacts (version + changelog + tree) committed separately on top, subject leading with the version
 - [ ] Every commit carries a body, and every body is one or two lines — none subject-only, none a paragraph
-- [ ] Annotated tag `v<version>` with structured markdown message, final line linking this version's changelog file
+- [ ] Release PR mode: branch pushed, PR open — title = release commit subject; body = theme line, `## Changes` in tag rules, `## Gates`, changelog link last (via `--body-file`, no closing keywords)
 - [ ] Working tree clean
-- [ ] Nothing pushed — local only
+- [ ] No tag at HEAD, nothing pushed to `main` — `release-and-publish` owns both