@cyanheads/mcp-ts-core 0.12.6 → 0.12.8

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.9"
+  version: "2.12"
   audience: external
   type: debug
 ---
@@ -17,7 +17,7 @@ Unit tests (`add-test` skill) verify handler logic with mocked context. Field te
 
 ### Transport coverage
 
-This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. The same handlers run on both transports — only the framing differs — so HTTP exercises the full functional surface.
+This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. The same handlers run on both transports — only the framing differs — so HTTP exercises the full functional surface. Both HTTP session modes are covered: a durable `Mcp-Session-Id` session, and the sessionless initialization a `MCP_SESSION_MODE=stateless` server performs.
 
 **Stdio coverage is a boot check only — run this before Step 1.** Run `bun run rebuild && bun run start:stdio`, confirm the startup logs look clean (banner, expected tool/resource counts, no errors/warnings, no missing-config gripes), then kill it. Pino logs go to stderr in stdio mode (stdout is reserved for JSON-RPC), so they print straight to the terminal when you run interactively. No need to call tools over stdio — the HTTP pass already covered handler behavior.
 
@@ -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,
@@ -93,9 +94,29 @@ mcp_start() {
   echo "ready pid=$pid url=$url port=$port log=$server_log"
 }
 
+# Internal: report a failed initialize with the raw exchange, then clean up.
+_mcp_init_fail() {
+  local msg="$1"; local body_file="$2"; local hdr="$3"
+  echo "init failed — $msg" >&2
+  echo "--- response body ---" >&2
+  if [ -s "$body_file" ]; then cat "$body_file" >&2; else echo "(empty)" >&2; fi
+  echo "--- response headers ---" >&2
+  if [ -s "$hdr" ]; then cat "$hdr" >&2; else echo "(none)" >&2; fi
+  rm -f "$hdr" "$body_file"
+  return 1
+}
+
 # Usage: mcp_init <url>
 # Runs `initialize`, sends `notifications/initialized`, prints:
-#   ready sid=<id> protocol=<negotiated-version>
+#   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
+# `protocol`: mcp_call takes the protocol as its 5th arg, which is what carries
+# the negotiated revision when there is no session to carry it.
 # A negotiated version older than the requested one means the server capped it
 # — note that in the report; you are then testing an older protocol than a
 # current client would use.
@@ -105,41 +126,91 @@ mcp_init() {
   local want="${MCP_FIELD_TEST_PROTOCOL:-2025-11-25}"
   local hdr; hdr=$(mktemp)
   local body_file; body_file=$(mktemp)
-  local code
+  local code curl_rc
   code=$(curl -sS -D "$hdr" -o "$body_file" -w '%{http_code}' -X POST "$url" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"$want\",\"capabilities\":{},\"clientInfo\":{\"name\":\"field-test\",\"version\":\"1.0.0\"}}}")
-  local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
-  if [ -z "$sid" ]; then
-    echo "init failed — HTTP $code, no Mcp-Session-Id header returned" >&2
-    echo "--- response body ---" >&2
-    cat "$body_file" >&2
-    echo "--- response headers ---" >&2
-    cat "$hdr" >&2
-    rm -f "$hdr" "$body_file"
+  curl_rc=$?
+  if [ "$curl_rc" -ne 0 ] || [ -z "$code" ] || [ "$code" = "000" ]; then
+    _mcp_init_fail "transport failure — curl exit $curl_rc, http_code '${code:-none}'; nothing listening at $url" "$body_file" "$hdr"
     return 1
   fi
-  local got; got=$(sed -n 's/^data: //p' "$body_file" | grep -o '"protocolVersion":"[^"]*"' | head -1 | cut -d'"' -f4)
-  [ -z "$got" ] && got=$(grep -o '"protocolVersion":"[^"]*"' "$body_file" | head -1 | cut -d'"' -f4)
-  curl -sS -X POST "$url" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json, text/event-stream" \
-    -H "Mcp-Session-Id: $sid" \
+  [ "$code" -ge 400 ] && { _mcp_init_fail "HTTP $code" "$body_file" "$hdr"; return 1; }
+  # Unwrap SSE framing when present; a plain JSON body is used as-is.
+  local payload; payload=$(sed -n 's/^data: //p' "$body_file")
+  [ -z "$payload" ] && payload=$(cat "$body_file")
+  local reply; reply=$(printf '%s\n' "$payload" | grep -E '"(result|error)"' | head -1)
+  [ -z "$reply" ] && reply="$payload"
+  if printf '%s' "$reply" | grep -q '"error"'; then
+    _mcp_init_fail "server returned a JSON-RPC error" "$body_file" "$hdr"
+    return 1
+  fi
+  if ! printf '%s' "$reply" | grep -q '"result"'; then
+    _mcp_init_fail "HTTP $code but no JSON-RPC result in the body" "$body_file" "$hdr"
+    return 1
+  fi
+  local got; got=$(printf '%s' "$reply" | grep -o '"protocolVersion":"[^"]*"' | head -1 | cut -d'"' -f4)
+  if [ -z "$got" ]; then
+    _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:-unknown} requested=$want (HTTP $code)"
+  echo "ready sid=$sid protocol=$got requested=$want instructions=${instr}B (HTTP $code)"
 }
 
-# Usage: mcp_call <url> <sid> <method> [JSON_PARAMS]
+# 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]
 # Prints the JSON-RPC response. SSE framing is stripped when present, and only
 # the reply is emitted (a single POST can also carry progress notifications, so
 # 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
+# server which revision the request speaks.
 mcp_call() {
-  local url="$1"; local sid="$2"; local method="$3"; local params="${4:-}"
-  [ -z "$url" ] || [ -z "$sid" ] || [ -z "$method" ] && { echo "usage: mcp_call <url> <sid> <method> [params]" >&2; return 1; }
+  local url="$1"; local sid="$2"; local method="$3"; local params="${4:-}"; local protocol="${5:-}"
+  [ -z "$url" ] || [ -z "$method" ] && { echo "usage: mcp_call <url> <sid> <method> [params] [protocol]" >&2; return 1; }
   local body
   if [ -z "$params" ]; then
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s"}' "$RANDOM" "$method")
@@ -147,13 +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
-  code=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$url" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json, text/event-stream" \
-    -H "Mcp-Session-Id: $sid" \
-    -d "$body")
+  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")
+  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
@@ -166,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)
@@ -241,11 +342,19 @@ Capture `pid`, `url`, `port`, `log` from the `mcp_start` output — every later
 mcp_init <url-from-mcp_start>
 ```
 
-Runs `initialize`, sends `notifications/initialized`, prints `sid=<id>` to capture for `mcp_call`, plus the protocol version the server negotiated.
+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`.
 
-This exercises the **2025-era arm**: `initialize` negotiates the revision, the server mints an `Mcp-Session-Id`, and every later call rides that session. The [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) is not in the `initialize` ladder at all — it is selected per request by the `io.modelcontextprotocol/protocolVersion` key in the request's own `_meta` envelope, and carries no session. Curl-based field testing therefore covers the sessionful leg; exercise the per-request leg from a real 2026-era client or an integration test.
+**`sid=` may come back empty — that is a pass, not a failure.** Under `MCP_SESSION_MODE=stateless` the server mints no `Mcp-Session-Id`, and the helper then omits the session header from every later request. Thread the empty value through positionally and pass the negotiated protocol, which is what identifies the revision when no session carries it:
+
+```bash
+mcp_call <url> '' tools/list '' <protocol-from-mcp_init>
+```
+
+To exercise both session modes, start the server twice — once with the project's default, once with `MCP_SESSION_MODE=stateless` — and run the same calls against each.
+
+Both modes exercise the **2025-era arm**: `initialize` negotiates the revision, and the session (when there is one) carries it. The [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) is a different thing from a sessionless 2025 handshake — it does not initialize at all, and is selected per request by the `io.modelcontextprotocol/protocolVersion` key in the request's own `_meta` envelope. This helper does not reach it; exercise the per-request leg from a real 2026-era client or an integration test.
 
 ### 3. Surface the catalog
 
@@ -254,8 +363,11 @@ This exercises the **2025-era arm**: `initialize` negotiates the revision, the s
 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:
@@ -277,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**
 
@@ -309,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.
 
@@ -334,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.
@@ -379,8 +496,10 @@ End with:
 
 - [ ] Stdio boot check completed — `bun run rebuild && bun run start:stdio` shows clean startup (banner, expected counts, no errors)
 - [ ] HTTP server built and started; real port parsed from log
-- [ ] Session initialized; `notifications/initialized` sent; negotiated protocol version matches the requested one (a downgrade is a finding)
+- [ ] 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
@@ -389,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.11"
+  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.
@@ -69,6 +81,7 @@ Every file that declares a version must be updated. Skip any file that doesn't e
 - `package.json` — `version`
 - `server.json` — top-level `version` AND every `packages[].version` entry
 - `manifest.json` (if present) — `version`. Verify `name` is the bare package name (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`)
+- `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` (if present) — `version`. Packaging validation fails on a mismatch; `.codex-plugin/mcp.json` is connection config and carries none
 - `README.md` — version badge
 - `CLAUDE.md` / `AGENTS.md` — if they pin a version string
 - `Dockerfile` — OCI labels if they pin the version
@@ -126,10 +139,19 @@ 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.
-2. **The release commit — last, on top.** Version bumps (`package.json`, `server.json`, README badge, `CLAUDE.md`/`AGENTS.md`), the changelog entry, `CHANGELOG.md`, and `docs/tree.md` go in a single final commit that sits on top of the work stack — never mixed into a feature commit.
+2. **The release commit — last, on top.** Version bumps (`package.json`, `server.json`, `manifest.json`, the plugin manifests, README badge, `CLAUDE.md`/`AGENTS.md`), the changelog entry, `CHANGELOG.md`, and `docs/tree.md` go in a single final commit that sits on top of the work stack — never mixed into a feature commit.
 
 Stage each group explicitly, commit it, then move to the next — the release commit goes last:
 
@@ -171,66 +193,81 @@ 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
 
 ## Checklist
 
 - [ ] Diff reviewed end-to-end before version bump
-- [ ] Version bumped in every declaring file (`package.json`, `server.json`, `manifest.json`, README badge, `CLAUDE.md`/`AGENTS.md` if they pin a version)
+- [ ] Version bumped in every declaring file (`package.json`, `server.json`, `manifest.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, README badge, `CLAUDE.md`/`AGENTS.md` if they pin a version)
 - [ ] GH issues addressed by this work commented with what landed (if working from GH issues)
 - [ ] Docs updated for any new or changed features
 - [ ] Changelog authored at `changelog/<major.minor>.x/<version>.md`
@@ -239,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

package/skills/orchestrations/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: workflow
 ---
@@ -51,14 +51,14 @@ A workflow file is the orchestrator's playbook for one run. Read it end-to-end b
 
 These apply to every workflow. Workflow files don't restate them; the orchestrator carries them forward and restates them in sub-agent prompts where applicable.
 
-1. **No commits, pushes, tags, branch creation, or destructive ops without explicit user authorization.** Work phases leave the working tree dirty for orchestrator review. Wrap-up and release phases run only after the user authorizes — though once authorized, the authorization is durable through the workflow's end (no re-asking at each phase boundary).
+1. **No commits, pushes, tags, branch creation, or destructive ops without explicit user authorization.** Work phases leave the working tree dirty for orchestrator review. Wrap-up and release phases run only after the user authorizes — though once authorized, the authorization is durable through the workflow's end (no re-asking at each phase boundary). The `release/<version>` branch and PR that `git-wrapup` creates in release PR mode are part of the authorized release, not a separate ask.
 2. **No `git stash`, no `git reset --hard`, no `git restore .`, no `git clean -f`, no `git checkout -- .`.** These bypass safety and risk silent data loss. Read-only git (`status`, `diff`, `log`, `show`, `blame`) is always safe.
 3. **No `--no-verify`, no `--no-gpg-sign`, no bypassing commit hooks.** If a hook fails, investigate the underlying issue.
 4. **`bun run devcheck` is the handoff gate between phases.** Work phases must hand back a green devcheck. If a phase can't reach green, halt and report the failing step verbatim rather than carrying broken state forward.
 5. **No marketing adjectives** in commits, tags, READMEs, or changelog entries — no "comprehensive", "robust", "enhanced", "seamless", "improved". State the change, not its quality.
 6. **One workflow per orchestration run.** Don't interleave two workflows in the same session. If a target needs both (e.g., maintenance surfaces a bug fix that needs field-testing first), sequence them as two workflow runs with a clean handoff in between.
 7. **`gh release create --notes-from-tag` is incompatible with `--repo`.** Always `cd` into the target repo directory for `gh release` commands.
-8. **Annotated tags only** (`git tag -a`), never lightweight, created with `--cleanup=whitespace` — the default (`strip`) deletes `#`-leading lines as comments; `--cleanup=verbatim` glues the SSH signature into the message (unparseable-as-signed tag, signature block leaks into the release body). Tag annotation subject omits the version number — GitHub prepends `v<VERSION>:` to release titles when using `--notes-from-tag`, so including the version in the subject creates stutter. The tag body's final line is a Markdown link to this version's changelog file — `[CHANGELOG v<VERSION>](https://github.com/<OWNER>/<REPO>/blob/main/changelog/<major.minor>.x/<VERSION>.md)`, separated from the gates line by a blank line — giving the release a one-click jump to the full entry.
+8. **Annotated tags only** (`git tag -a`), never lightweight, created with `--cleanup=whitespace` — the default (`strip`) deletes `#`-leading lines as comments; `--cleanup=verbatim` glues the SSH signature into the message (unparseable-as-signed tag, signature block leaks into the release body). Tag annotation subject omits the version number — GitHub prepends `v<VERSION>:` to release titles when using `--notes-from-tag`, so including the version in the subject creates stutter. The tag body's final line is a Markdown link to this version's changelog file — `[CHANGELOG v<VERSION>](https://github.com/<OWNER>/<REPO>/blob/main/changelog/<major.minor>.x/<VERSION>.md)`, on its own paragraph — giving the release a one-click jump to the full entry; in release PR mode that line continues with ` · release PR #<N>` so the release also points at its audit trail.
 9. **Conventional Commits subjects** (`feat|fix|refactor|chore|docs|test|build(scope): message`). One logical concern per commit. The release commit (version bump + changelog + regenerated artifacts) lands on top of a stack of feature/fix commits, never collapsed alongside them.
 10. **Email on any artifact is the user's domain email**, never a personal address that might appear in git config.
 
@@ -161,7 +161,17 @@ For N targets in a phase:
 
 ### Editor / wrap-up separation
 
-Editing phases and wrap-up phases never go in the same sub-agent. Editing sub-agents make file changes and run devcheck — they do not commit, tag, or push. Wrap-up sub-agents read the working tree, commit, tag, and (when releasing) push and publish — they do not edit source. This separation lets the orchestrator review diffs before they become permanent and keeps the commit graph clean.
+Editing phases and wrap-up phases never go in the same sub-agent. Editing sub-agents make file changes and run devcheck — they do not commit, tag, or push. Wrap-up sub-agents read the working tree, commit, and (when releasing) tag, push and publish — they do not edit source. This separation lets the orchestrator review diffs before they become permanent and keeps the commit graph clean.
+
+### Release PR mode
+
+A target can declare that every release goes through a pull request (in its `CLAUDE.md`/`AGENTS.md`, or in the run's brief — mechanics in `git-wrapup`'s "Release PR mode"). The wrap-up + release phase then runs as **three sub-agents in sequence**, with an orchestrator check between each:
+
+1. **Wrap-up** — `git-wrapup`; halts with the stack committed on `release/<version>`, pushed, PR open.
+2. **Review** — `release-pr-review`; reads the PR range through `code-simplifier` plus a correctness review, lands fixes as fixup commits autosquashed into the stack, force-with-lease pushes the release branch, syncs the PR body, leaves one summary comment. This is the one role that both edits and commits — scoped to the release branch, never `main`, never a tag.
+3. **Release** — `release-and-publish`; `git merge --ff-only` onto `main` locally, tags `main`'s tip, pushes, publishes. Its brief must state that the review pass is finished — the skill halts without that line, and the orchestrator writes it only after confirming the review agent's report against the PR (`gh pr view --json state,headRefOid`, `git log --oneline main..HEAD`).
+
+Straight-through mode drops the review agent: one sub-agent runs wrap-up and release back to back, opening and merging the PR in the same session. Without a declaration there is no PR, and the stack lands on `main` directly.
 
 ### Normalization
 
@@ -186,10 +196,11 @@ Sub-agent self-reports describe intent, not always reality. After every phase th
 - **Files** — `ls`, `git status`, `git diff --stat`
 - **Commits** — `git log --oneline -5`
 - **Tags** — `git tag --points-at HEAD`, `git ls-remote --tags origin`
+- **Release PR** — `gh pr view <N> --json state,headRefOid` (`OPEN` with head == local HEAD between phases; `MERGED` after release), `git ls-remote --heads origin release/<VERSION>` empty after release
 - **GitHub** — `gh repo view --json visibility`, `gh release view v<VERSION>`, `gh issue list`, `gh issue view <N> --comments` to confirm the fix comment landed
 - **npm / registries** — `npm view <pkg>@<version>`, registry-specific checks
 - **Build state** — re-run `bun run devcheck` if the previous phase was supposed to land green
-- **Quality** — tag annotation is a headline digest covering every change (flat bullets — notable ones named, minor ones in one grouped bullet; no changelog section headers, deps ≤1 line, no gates line), subject omits the version number, no marketing adjectives, issue backlinks where applicable, changelog link as final line
+- **Quality** — tag annotation is a headline digest covering every change (flat bullets — notable ones named, minor ones in one grouped bullet; no changelog section headers, deps ≤1 line, no gates line), subject omits the version number, no marketing adjectives, issue backlinks where applicable, changelog link as final line (plus ` · release PR #<N>` in release PR mode)
 
 If verification disagrees with the sub-agent's report, that's the signal to re-spawn with the actual state and the unmet goal in the prompt — not to trust the report. The goal hasn't changed; only the path needs to.
 
@@ -200,7 +211,7 @@ If verification disagrees with the sub-agent's report, that's the signal to re-s
 | Reads, analysis, file edits (working tree only) | Implicit — initial workflow approval covers these |
 | Local commits, annotated tags | Explicit at workflow start; durable through workflow end |
 | Push to remote, npm / registry publish, GH release create, Docker push | Explicit at workflow start; durable through workflow end |
-| Destructive ops (force push, tag delete, remote branch delete, etc.) | Always re-confirm, never assume |
+| Destructive ops (force push, tag delete, remote branch delete, etc.) | Always re-confirm, never assume — two exceptions ride the release authorization: `release-pr-review`'s `--force-with-lease` on the run's own unmerged `release/<version>` branch, and `release-and-publish` deleting that branch once the PR reports `MERGED` |
 
 Pipeline authorization is durable through to completion. Once the user authorizes a workflow run, don't re-ask at each phase boundary — proceed automatically through gates that pass. Conditions that always require a fresh check-in: destructive ops on shared resources, external actions without sign-off, errors that need human judgment.