review: split performance-db-cost.md and api-contracts.md into cores plus lazy references

.claude/skills/INDEX.md

@@ -98,6 +98,7 @@ Run `python3 <skill>/scripts/<name>` (`bash` for `.sh`). `name: purpose — argu
 
 ### communication-structure
 - comms_lint.py: score a human-facing draft against its artifact template. — --kind K [--file F] [--source S]…
+- reader_check.py: Reader-accuracy check: can a reader answer fixed factual… — --checks evals/reader-checks.json --id…
 - status_update_lint.py: check a leadership status update against… — --file F
 - status_vocab_lint.py: flag unverified "live"/"done" claims in a human-facing update. — --file F
 
@@ -123,6 +124,7 @@ Run `python3 <skill>/scripts/<name>` (`bash` for `.sh`). `name: purpose — argu
 - post_review.sh: post review findings to a PR (opt-in). — <PR-number> <findings.json> [--post]
 - review_checks.sh: run local, read-only analyzers over the files changed since… — [--base REF] [--tests] [--timeout SECS]
 - score_review.py: Score a review's findings against a ground-truth file: recall… — GROUND_TRUTH.json FINDINGS.json…
+- security_verify.py: triage security findings: verify-or-drop plus a tunable… — [findings.json|-] [override-file]
 - token_differ.py: the tier-1 design<->app design-token VALUE parity gate. — --design <file> --app <file> [--map…
 - No documented CLI: binaries_gate.py, ci_cost_lint.py, closes_lint.py, reaper_lint.py, review_feedback.py, source_scan_tests.py, validate_status_claims.py
 

.claude/skills/communication-structure/INDEX.md

@@ -6,13 +6,14 @@ Generated by `scripts/skill_index.py` (do not hand-edit; rerun it after changing
 
 | File | Read this when... | Tok |
 |---|---|---|
-| `references/artifact-templates.md` | you draft a status update, PR body, release note, decision memo or executive summary, incident summ… | 1739 |
+| `references/artifact-templates.md` | you draft a status update, PR body, release note, decision memo or executive summary, incident summ… | 1757 |
 | `references/leadership-status-update.md` | you write any status update a non-technical leader will read: a tracker project update, an issue st… | 500 |
 
 ## Scripts
 
 | File | Trigger | CLI (— = open the header) |
 |---|---|---|
 | `scripts/comms_lint.py` | score a human-facing draft against its artifact template. | comms_lint.py --kind K [--file F] [--source S] [--json] \| --list |
+| `scripts/reader_check.py` | Reader-accuracy check: can a reader answer fixed factual questions from a message alone? | reader_check.py --checks evals/reader-checks.json --id held02 --file message.md Prints "<passed>/<total>" and each fail… |
 | `scripts/status_update_lint.py` | check a leadership status update against references/leadership-status-update.md. | status_update_lint.py --file F |
 | `scripts/status_vocab_lint.py` | flag unverified "live"/"done" claims in a human-facing update. | status_vocab_lint.py --file F |

.claude/skills/deep-code-review/INDEX-scripts.md

@@ -25,6 +25,7 @@ Generated by `scripts/skill_index.py` (do not hand-edit). The script half of `IN
 | `scripts/review_checks.sh` | run local, read-only analyzers over the files changed since REF (default origin/main, compared as R… | review_checks.sh [--base REF] [--tests] [--timeout SECS] |
 | `scripts/review_feedback.py` | repo-local accept/dismiss ledger for review findings. | — |
 | `scripts/score_review.py` | Score a review's findings against a ground-truth file: recall and precision under an FP budget. | score_review.py GROUND_TRUTH.json FINDINGS.json [--max-fp N] |
+| `scripts/security_verify.py` | triage security findings: verify-or-drop plus a tunable exclusion list. | security_verify.py [findings.json\|-] [override-file] Input: JSON list of findings on stdin or a file. Each row may carr… |
 | `scripts/source_scan_tests.py` | flag a "test" that reads UI source as TEXT instead of rendering it, the class of test that cannot o… | — |
 | `scripts/token_differ.py` | the tier-1 design<->app design-token VALUE parity gate. | token_differ.py --design <file> --app <file> [--map <tsv>] [--root-px 16] [--min-pairs N] token_differ.py --selftest |
 | `scripts/validate_status_claims.py` | Flag a completion status that carries a caveat — "a ✅ that needs an asterisk is a ✗". | — |

.claude/skills/deep-code-review/INDEX.md

@@ -26,6 +26,7 @@ Generated by `scripts/skill_index.py` (do not hand-edit; rerun it after changing
 | `references/appsec-ssti.md` | the target or diff compiles a server-side template from anything but a static file: render_template… | 507 |
 | `references/appsec-supply.md` | the target or diff adds or bumps a dependency, touches a lockfile or an install-time script, edits… | 2623 |
 | `references/appsec-tokens.md` | the target or diff issues or verifies JWTs, implements OAuth or OIDC, rotates refresh tokens, or mi… | 1749 |
+| `references/appsec-verify.md` | you are about to report a security finding, when a project asks to tune which low-signal security c… | 1444 |
 | `references/billing-correctness.md` | the target meters usage, runs subscriptions, charges cards, handles invoices or tax, or processes r… | 2168 |
 | `references/branch-and-merge-hygiene.md` | Read this on a FULL / repo-level review of a git repo with more than one branch, or whenever the re… | 7979 |
 | `references/code-structure.md` | the review judges module boundaries or coupling: a FULL review of a codebase that has grown past on… | 1612 |
@@ -75,7 +76,7 @@ Generated by `scripts/skill_index.py` (do not hand-edit; rerun it after changing
 | `references/full-audit.md` | the scope is FULL (never for DIFF or FILE). | 1646 |
 | `references/full-map-principles.md` | a finding turns on principle 4-6, 10 or 11 (1-3 and 7-9 stay in full-map.md), or when setting or re… | 765 |
 | `references/full-map-report.md` | writing the Phase 5 report or closing a review (Definition of done (a)). | 504 |
-| `references/full-map.md` | the review is FILE or FULL scope, a DIFF over 300 changed lines or with a blast-radius flag, or any… | 4680 |
+| `references/full-map.md` | the review is FILE or FULL scope, a DIFF over 300 changed lines or with a blast-radius flag, or any… | 4685 |
 | `references/i18n-l10n.md` | the target renders user-facing text in more than one language or locale, accepts user-supplied Unic… | 2540 |
 | `references/infra-evolution-by-stage.md` | the going-forward roadmap (report-format.md) must advise how a project's infrastructure and archite… | 1971 |
 | `references/infra-iac-containers.md` | the target ships Dockerfiles, Kubernetes manifests/Helm, Terraform/Pulumi/CloudFormation, CI/CD wor… | 4342 |
@@ -119,7 +120,8 @@ Generated by `scripts/skill_index.py` (do not hand-edit; rerun it after changing
 | `references/security-agent-skills.md` | the target is a skill, installs skills, or loads skill files (SKILL.md, skill.json, manifest.json,… | 1627 |
 | `references/security-ai-agents.md` | the code calls an LLM, embeds/retrieves (RAG), or runs an agent that plans, calls tools, executes c… | 9786 |
 | `references/security-api.md` | the target serves its own HTTP, GraphQL, gRPC, or WebSocket API (always for api / service) | 4361 |
-| `references/security-appsec.md` | Read when the target exposes any network surface (web app, API, service, CLI touching untrusted inp… | 6989 |
+| `references/security-appsec.md` | Read when the target exposes any network surface (web app, API, service, CLI touching untrusted inp… | 7029 |
+| `references/security-review-mode.md` | the user asks for a security audit or security review of a whole app (not a diff). | 2697 |
 | `references/skill-authoring-and-size.md` | the target repository ships or installs agent skills (/SKILL.md, .claude/skills/, .cursor/skills/,… | 991 |
 | `references/standards-index.md` | citing a standard URL or verification date from an installed copy of the skill. | 117 |
 | `references/testing-ai-evals.md` | the target calls an LLM, retrieves for generation (RAG), or runs a tool-using agent. | 2564 |
@@ -142,4 +144,4 @@ Generated by `scripts/skill_index.py` (do not hand-edit; rerun it after changing
 
 ## Scripts
 
-24 scripts. Read `INDEX-scripts.md` when you need a script (a trigger and CLI per script). `../INDEX.md`, `### deep-code-review`, has only each one-line purpose and arguments.
+25 scripts. Read `INDEX-scripts.md` when you need a script (a trigger and CLI per script). `../INDEX.md`, `### deep-code-review`, has only each one-line purpose and arguments.

.claude/skills/deep-code-review/references/api-contracts-streaming.md

@@ -0,0 +1,74 @@
+# Streaming transports — contract & reliability
+
+Read this when the target serves or consumes a WebSocket, SSE or gRPC-streaming endpoint (server, client or SDK wrapper). It fires at FILE or FULL scope on what the repo contains, not only on a diff. Moved verbatim from `api-contracts.md`, where "this file" refers; the auth angle stays in `security-api.md`.
+
+A live push connection is neither a queue nor an outbound call; its own failure modes need their own
+review. (The auth angle — upgrade auth, `Origin`/CSWSH, per-connection limits — is in `security-api.md`, the WebSocket paragraph; not restated here.) The same
+failure modes apply to **gRPC streaming** (server-streaming, client-streaming, bidi) — a live push
+connection over HTTP/2 instead of a WS/SSE handshake, sharing the reconnect/backpressure/liveness concerns
+below; `security-api.md`'s gRPC paragraph owns its authz/TLS half, not restated here either. (The
+horizontal-scale angle — an in-process connection/subscription registry that silently stops delivering
+once the server is replicated — is `concurrency-shared-state.md`'s shared-mutable-resource-scope bullet;
+not restated here.)
+
+- **Reconnection resumes from the last delivered position — not from scratch, not silently gapped.** A
+  connection *will* drop (NAT/proxy timeout, deploy, blip). SSE gives a resume primitive: the client
+  re-sends its last id ("`Set (Last-Event-ID, lastEventIDValue) in request's header list`") and the
+  server must honor it to replay the gap. WebSocket has **no** built-in resume, so the application must
+  carry an equivalent cursor/sequence and catch up on reconnect. Give the reconnect a bounded backoff
+  (SSE's own reconnection time "must initially be an implementation-defined value, probably in the region
+  of a few seconds," with "an exponential backoff delay" on repeated failure) **plus jitter** — that
+  backoff schedule assumes only *this* client is failing; it does not survive a **server-side
+  mass-disconnect** (a deploy, restart, or rolling update drops every open connection at the same
+  instant), where every client's exponential schedule anchors to the identical drop time and retries **in
+  lockstep**, re-storming the server the moment it comes back. Randomizing each client's wait inside its
+  backoff window spreads the reconnects out instead. This is a different correlation source than a single
+  client's own retry jitter (`reliability-error-handling.md`, which spreads *one* caller's repeated
+  retries) or a cache-key stampede on expiry (`performance-db-cost.md`, which correlates independent
+  callers on a shared *key*); here the **server's own restart is the synchronizer**, correlating
+  otherwise-unrelated clients on a shared *instant*. Worth
+  naming because the spec doesn't: the WHATWG page this bullet already cites describes the backoff but
+  stops short of jitter. 🚩 an SSE server that never reads `Last-Event-ID`; a
+  WS reconnect that just re-subscribes with no catch-up; a reconnect backoff with no jitter (fine for one
+  client, a synchronized re-storm risk after a fleet-wide drop).
+- **Bound a slow consumer — never let one connection grow server memory without limit.** The backpressure
+  discipline required for queues (`domain-w.md`) applies *per live connection*: a server fanning
+  out to N clients where one reads slowly must cap that connection's send buffer and pick a policy —
+  drop-oldest, coalesce, or disconnect — not queue unboundedly. On the browser send side, a
+  high-frequency `send()` loop must watch `bufferedAmount` ("the number of bytes ... queued using
+  `send()` but ... not yet ... transmitted") and pace to it, not fire blindly.
+- **Check liveness both ways, with a timeout policy — not just "ping is available."** A vanished client
+  (phone sleep, NAT drop) holds a connection slot and its subscriptions open forever unless you detect
+  it: send pings on an interval, track outstanding pongs, reclaim on timeout. RFC 6455: a Ping "may serve
+  either as a keepalive or as a means to verify that the remote endpoint is still responsive," and "Upon receipt of a Ping frame, an endpoint MUST send a Pong frame in response, unless it already received a Close frame" — but the spec is silent on a
+  *missed* pong, so closing/reclaiming on one is the application's job. 🚩 a server that pings but never
+  acts on a missing pong.
+- **Ordering and dedup are an explicit contract across a reconnect.** The transport delivers messages in order *within* one connection (WebSocket runs over TCP, SSE over one long-lived HTTP response), but that guarantee ends at the connection boundary — a resumed stream can overlap what the client already
+  processed. Give each message a stable id/sequence and make the consumer idempotent on it: the same
+  at-least-once + idempotent-consumer rule this file states for queues/webhooks, applied to a resumed
+  live stream.
+- **gRPC's own keepalive can get the *sender* killed, not the peer — match both sides' policy.** A client
+  sending aggressive HTTP/2 keepalive pings on a sparse, long-lived streaming RPC is not automatically
+  welcome: gRPC's keepalive guide warns: "If the service does not support keepalive, the first few
+  keepalive pings will be ignored, and the server will eventually send a `GOAWAY` message with debug data
+  equal to the ASCII code for `too_many_pings`." The defaults invite exactly this mismatch — the client's
+  own ping interval (`KEEPALIVE_TIME`) defaults to disabled (`INT_MAX (Disabled)`), while a server's
+  minimum-allowed gap between pings carrying no data (`PERMIT_KEEPALIVE_TIME`) defaults to `300000 (5
+  minutes)` and `PERMIT_KEEPALIVE_WITHOUT_CALLS` defaults to `0 (false)` — so enabling aggressive
+  client-side keepalive with no matching server-side allowance gets the connection killed by the peer the
+  ping was meant to keep it alive against. (The keepalive guide states the `GOAWAY` behavior and the
+  `PERMIT_KEEPALIVE_TIME` default separately; the *connecting* mechanism — a server counts a `ping_strike`
+  for each ping arriving before `PERMIT_KEEPALIVE_TIME` has elapsed and, once strikes pass
+  `MAX_PING_STRIKES`, sends `GOAWAY` with `ENHANCE_YOUR_CALM` / `too_many_pings` — is spelled out in gRPC
+  proposal **A8, client-side keepalive**.) Distinct from the RFC 6455 ping/pong above: that is each side
+  **detecting the other is gone**, at the WS-frame layer; this is **your own liveness probe getting you
+  disconnected** by a healthy, default-configured peer, at the HTTP/2 PING-frame layer. 🚩 client
+  keepalive enabled with no corresponding server `PERMIT_KEEPALIVE_TIME` / `PERMIT_KEEPALIVE_WITHOUT_CALLS`
+  allowance (or the reverse).
+- **A bidi-streaming RPC can deadlock itself under manual flow control.** gRPC's flow-control guide:
+  "There is the potential for a deadlock if both the client and server are doing synchronous reads or
+  using manual flow control and both try to do a lot of writing without doing any reads." Flow control
+  "applies to streaming RPCs and is not relevant for unary RPCs," and gRPC manages it for you by default —
+  the risk is specifically code that opts into **manual** flow control (or blocking synchronous reads) on
+  **both** ends of a bidi stream and keeps writing without ever draining its own read side. 🚩 a
+  bidi-streaming handler, on either end, that writes in a loop with no interleaved read.