@opengroundplan/core 0.1.1

package/registry/skills/onboard/references/discovery-checklist.md

@@ -0,0 +1,129 @@
+# Discovery checklist
+
+Outside-in. Stop when you can fill the map — completeness of exploration is not the goal, an accurate map is.
+
+---
+
+## 1. Shape
+
+- [ ] Top-level directories, and which hold source vs tooling vs generated output
+- [ ] Package/project manifests — how many, and do they declare a workspace?
+- [ ] Lockfiles present? (their absence is itself a finding)
+- [ ] Version control config: ignored paths, attributes, hooks directory
+- [ ] CI definitions — these are the most honest documentation in any repo: they say what actually has to pass
+
+**Signal:** multiple manifests + a workspace field = monorepo. Read the workspace globs to learn the real package list, not the folder names.
+
+---
+
+## 2. Entry points
+
+Find where execution *begins*. Ranked by reliability:
+
+- [ ] Manifest-declared entries: `main`, `bin`, `scripts.start`, project startup object, module entry
+- [ ] CI/deploy definitions — what command does production actually run?
+- [ ] Container or process definitions
+- [ ] Framework conventions (a routes directory, a pages directory, a handler registry)
+- [ ] Files named for bootstrapping: main, index, app, server, program, cli, worker, entry
+
+For each, note what it wires. The entry point is where you learn the composition root, the config load, and the shutdown path — three things nothing else tells you.
+
+**Trap:** the largest file is rarely an entry point. Do not confuse "where the code is" with "where it starts".
+
+---
+
+## 3. Module boundaries
+
+- [ ] `boundaries[]` in `AGENTS.md` — if declared, this is the answer; verify rather than infer
+- [ ] Architecture style from directory names (see architecture-guard's `boundary-patterns.md`)
+- [ ] Any machine-enforced rules: dependency linting, module visibility, layer plugins, architecture tests
+- [ ] Public surfaces: barrels, index files, `api/`, `contracts/`, explicit export lists
+- [ ] Actual import directions in 3-4 representative files — does the code obey the implied shape?
+
+**Signal:** a `shared/`, `common/`, or `utils/` that imports from feature directories means the boundary is already inverted, whatever the folder names claim.
+
+**Report the disagreement.** "Declared clean architecture; the domain imports the ORM in four places" is one of the most valuable lines a map can contain.
+
+---
+
+## 4. Tests
+
+- [ ] Location pattern — co-located with source, a parallel tree, or both
+- [ ] File naming convention
+- [ ] Test framework, from the manifest
+- [ ] Which layers exist: unit, integration, contract, e2e — and which are thin or empty
+- [ ] What the default test command actually runs (often not everything)
+- [ ] Fixtures, factories, builders — how test data gets made
+- [ ] External dependencies for integration tests: containers, a live service, a seeded database
+- [ ] Whether tests are in CI, and whether CI is required to merge
+
+**Signal:** a repo with 400 unit tests and no integration tests has a different real convention than its README claims. Test layout is the most honest statement of what a team believes it must verify.
+
+**Trap to record:** any test suite that only passes after an undocumented setup step.
+
+---
+
+## 5. Commands
+
+- [ ] `AGENTS.md` `commands.*` — the source of truth
+- [ ] If absent: manifest scripts, task-runner files, CI steps
+- [ ] Which one CI actually runs on a pull request (that is the real gate)
+- [ ] Run them if the environment allows. A verified command is 🟢; an unverified one is 🟡 at best
+
+Never invent a command from stack conventions and present it as fact. If the repo does not declare one and you cannot run it, mark 🔴 and list it under Gaps.
+
+---
+
+## 6. Config and secrets
+
+- [ ] Where settings resolve — a config module, a settings object, an env loader
+- [ ] Whether there is **one** place holding typed defaults, or defaults scattered at call sites (the latter is a finding)
+- [ ] Required env vars with no default, and the failure mode when they are missing
+- [ ] Example env files, and how far they drift from what the code reads
+- [ ] Ignored files that hold real values — name them so nobody commits one
+- [ ] Feature flags and where they are evaluated
+
+**Signal:** literal URLs, ports, timeouts, or model ids inside business logic. Report it — it is both a trap for the next agent and a convention violation worth recording.
+
+---
+
+## 7. Traps
+
+Only with evidence. Sources, in order of reliability:
+
+- [ ] CI steps that exist purely to work around something
+- [ ] Setup or bootstrap scripts, and what they do beyond installing
+- [ ] Comments containing warnings, workarounds, or "do not"
+- [ ] Generated directories the build requires but does not create
+- [ ] Deprecated modules still present next to their replacements
+- [ ] Migration or codegen ordering that nothing enforces
+- [ ] Anything that failed when *you* ran it
+
+Record: the trap, the evidence, and the workaround. Drop anything you cannot evidence.
+
+---
+
+## 8. Recorded knowledge
+
+- [ ] `docs/adr/` — the last few accepted records; the ADR index in `AGENTS.md` is the fast path
+- [ ] `.agent/DECISIONS.md` — working reasoning
+- [ ] `.agent/DONE.md` — recent completed work shows the team's actual rhythm
+- [ ] `specs/` — the most recent 2-3 specs show how work is scoped here
+- [ ] Recent history — the files that change together tell you the real module boundaries, whatever the folders say
+
+**Do not re-derive what is written down.** If an ADR explains the storage choice, cite it; do not reconstruct the reasoning from the schema.
+
+---
+
+## Stop conditions
+
+Stop and report rather than continuing to dig when:
+
+- `AGENTS.md` is accurate — say so and switch to gap-filling.
+- The declared commands fail — that blocks everything; report first.
+- The repo is far larger than the question asked — switch to a scoped map.
+- Two sources of truth conflict — report the conflict; do not silently pick.
+
+## Time-boxing
+
+Fill the map's required sections first, then deepen only where the user's actual question lives. A complete map of an area nobody asked about is wasted work, and an exhaustive sweep produces a document too long to read — which is the same as no map at all.

package/registry/skills/onboard/references/repo-map-template.md

@@ -0,0 +1,120 @@
+# Repo map template
+
+The written deliverable. One page. Every claim carries a confidence tag: 🟢 verified by reading or running · 🟡 inferred from structure · 🔴 assumed from convention.
+
+---
+
+```markdown
+# Repo map — <repo name>
+
+**What it is:** <one sentence. What does this system do, for whom.> 🟢
+
+**Shape:** <monorepo with N packages | single package | app + library> 🟢
+**Primary stack:** <languages, runtime, major frameworks> 🟢
+**AGENTS.md:** <present and accurate | present but stale in N places | absent>
+
+## Read these five first
+
+1. `<path>` — <why: what this single file teaches you>
+2. `<path>` — <why>
+3. `<path>` — <why>
+4. `<path>` — <why>
+5. `<path>` — <why>
+
+<If a standard role has no file, say so: "No single composition root — wiring is
+distributed across each module's registration file." That absence is a finding.>
+
+## Entry points
+
+| Surface | Entry file | Notes |
+|---|---|---|
+| <HTTP server / CLI / worker / job / build> | `<path>` | <what it wires up> |
+
+<Execution begins here — not where the most code lives.>
+
+## Module boundaries
+
+**Declared:** <the `boundaries[]` entries from AGENTS.md, or "none declared">
+**Observed style:** <layered / clean / hexagonal / vertical-slice / modular-monolith / FSD / none> 🟡
+
+| Zone | Path | Depends on | Notes |
+|---|---|---|---|
+| <name> | `<dir>/` | <zones> | <public surface, if any> |
+
+<If observed structure and declared boundaries disagree, say so here and route to
+architecture-guard. Do not quietly pick one.>
+
+## Tests
+
+- **Location:** <co-located / separate tree / both> — `<path pattern>` 🟢
+- **Naming:** `<pattern observed>` 🟢
+- **Layers covered:** <unit / integration / e2e — and which are thin> 🟡
+- **Run via:** the declared `commands.test` in AGENTS.md
+- **Fixtures / factories:** `<path>` — <how test data is built>
+- **Notable:** <e.g. integration tests need a running dependency; e2e is not in the default run>
+
+## Commands
+
+Read from `AGENTS.md` `commands.*`. Never restate literals here — reference by name.
+
+| Purpose | Declared? | Verified? |
+|---|---|---|
+| build | yes/no | 🟢 ran it / 🟡 read from manifest / 🔴 guessed |
+| test | | |
+| lint | | |
+| typecheck | | |
+| dev | | |
+
+<Any row that is 🔴 or "no" is a gap to fix in AGENTS.md before agent work starts.>
+
+## Config and secrets
+
+- **Settings resolve through:** `<path>` — <env-first? typed defaults? where the single default table lives> 🟢
+- **Required to start:** <env vars with no default; what fails if missing>
+- **Never commit:** <the ignored files that hold real values>
+- **Protected paths:** <from AGENTS.md `protectedPaths[]`, or "none declared">
+
+## Traps
+
+Evidence-backed only. One line each. Omit the section if there are none.
+
+- <trap> — evidence: <the comment / script / CI step / failure you actually saw>
+
+## Gaps
+
+What you could not determine, and what it would take to find out.
+
+- <unknown> — <what would answer it>
+
+## Proposed AGENTS.md updates
+
+For approval. Do not write these without it, and do not create a parallel doc.
+
+- `overview` — <proposed text>
+- `commands.*` — <entries to add or correct>
+- `conventions[]` — <only conventions that differ from language defaults>
+- `boundaries[]` — <proposed rules, if the shape is clear and nothing is declared>
+- `protectedPaths[]` — <generated, vendored, or migration paths agents must not edit freely>
+```
+
+---
+
+## Length discipline
+
+If the map runs past one page:
+
+- The five-files list has grown past five. Cut back — ranking is the value.
+- The zone table lists directories rather than zones. A zone is a boundary, not a folder.
+- Traps include general advice. Traps are surprises, not conventions.
+- You are explaining *how the code works* rather than *where things are*. That is a different deliverable.
+
+## What never goes in the map
+
+| Content | Belongs in |
+|---|---|
+| Literal build/test commands | `AGENTS.md` `commands.*` |
+| Style and naming rules | `AGENTS.md` `conventions[]` |
+| Why a design choice was made | `docs/adr/` |
+| Current task state | `.agent/ACTIVE.md` / `HANDOFF.md` |
+| Requirements | `specs/NNN-slug/spec.md` |
+| A full file listing | Nothing. That is not a map, it is a directory listing. |

package/registry/skills/onboard/skill.yaml

@@ -0,0 +1,7 @@
+id: onboard
+kind: skill
+name: Repo Onboarding Map
+description: Map an unfamiliar repo for a fresh agent — entry points, module boundaries, tests, commands, the five files to read first, and known traps.
+tags: [onboarding, discovery, documentation, repo-map]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/registry/skills/perf-budget/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: perf-budget
+description: "Check a change against the project's declared performance budgets — LCP/INP/CLS, bundle size, p95/p99 latency. Use when the user says performance budget, is this too slow, bundle size, web vitals, did this regress performance, latency check, /verify performance. Budgets are read from project config, never invented here. NOT for micro-optimizing code."
+metadata:
+  version: 1.0.0
+  category: performance
+  updated: 2026-07-18
+---
+
+# Performance Budget Check
+
+You are an expert at holding a change to the performance limits the team actually agreed to. Your goal is a verdict against **declared** budgets with **measured** numbers — not an opinion about what looks slow.
+
+## Before Starting
+
+Find the declared budgets. **This skill contains no numbers.** Precedence, highest first:
+
+1. A budgets file in the project (a performance-budget config, a bundle-size limit config, an SLO definition).
+2. `AGENTS.md` — the agent-kit's declared performance rules and the `commands.*` entry that measures them.
+3. CI configuration — a step that fails on a threshold is a declared budget, wherever it is written.
+
+If none exist, **stop and say so**. Do not invent a number. Report what the change appears to affect, and propose a budget set for the team to declare — see [references/budget-catalog.md](references/budget-catalog.md) for the categories worth declaring and what each is normally measured against.
+
+## The core rule
+
+> **A budget without a measurement source is a wish.**
+
+Every budget must name three things: the **metric**, the **limit**, and **where the number comes from**. A limit nobody measures cannot be exceeded, cannot be enforced, and will be discovered as broken by a user rather than by CI.
+
+For every budget you check, answer:
+
+| Question | If unanswerable |
+|---|---|
+| What exactly is measured? | The budget is ambiguous — flag it |
+| Where does the number come from? | It is a wish, not a budget — say so |
+| Under what conditions? (device, network, dataset, concurrency) | Numbers are not comparable — flag it |
+| Is it measured automatically, or by someone remembering? | Manual means it stops happening |
+
+A budget that fails these is reported as **UNMEASURABLE**, not as PASS. Reporting PASS on an unmeasured budget is the worst output this skill can produce — it manufactures confidence.
+
+Measurement sources, their trust level, and what each can and cannot tell you: [references/measurement-sources.md](references/measurement-sources.md).
+
+## How This Skill Works
+
+**Mode 1 — Check a change.** Does this diff regress a declared budget? Needs a before and an after from the same source under the same conditions.
+
+**Mode 2 — Audit budgets.** Are the declared budgets meaningful and measured? Produces a per-budget health report: declared, measured, enforced, or wishful.
+
+**Mode 3 — Propose budgets.** Nothing declared. Recommend categories and measurement sources based on what the project actually is, then hand it to the team to declare. You propose the *structure*; they choose the *numbers*.
+
+## Web vitals
+
+Three user-centric metrics. Each is a **distribution across real sessions**, not a single number — a budget stated without a percentile is under-specified.
+
+- **LCP** (Largest Contentful Paint) — when the main content appears. Regressed by: render-blocking resources, unoptimized hero images, slow server response, client-side rendering of above-the-fold content, font loading strategy.
+- **INP** (Interaction to Next Paint) — responsiveness across *all* interactions in a session, replacing the old first-interaction metric. Regressed by: long tasks, heavy event handlers, large re-render trees, synchronous work on the main thread.
+- **CLS** (Cumulative Layout Shift) — visual stability. Regressed by: images and embeds without reserved dimensions, injected banners, late-loading fonts causing reflow, content inserted above existing content.
+
+Diff-level signals for each are in the catalog. Budgets are met at a **percentile of real users** (field data), not on your machine — a lab number is a useful early signal and is not the budget.
+
+## Bundle size
+
+The budget that is easiest to enforce and easiest to erode — nobody notices a fifth kilobyte, and there are always five more.
+
+Check per changed entry point or route:
+- Total transferred size and **uncompressed parse size** — parse cost tracks the uncompressed number, and on mid-range devices parsing is the expensive part.
+- New dependencies and their real cost after tree-shaking, not their advertised size.
+- Whether a heavy import landed on a critical path that was previously lazy.
+- Duplicate copies of the same library at different versions.
+- Polyfills and locale/icon data pulled in wholesale.
+
+Budget per route or per entry point. A single app-wide total lets one route quietly absorb every regression.
+
+## Backend latency — percentiles, never averages
+
+**Never budget on an average.** An average hides exactly the users you care about: a mean of 100ms is consistent with 95% of requests at 40ms and 5% at 1.2 seconds, and those 5% are the ones filing tickets. The average is also unstable — one outlier moves it, and it cannot be aggregated across services without lying.
+
+Budget on **p95** and **p99**:
+
+- **p95** — the normal bad case. Where most user-visible slowness lives.
+- **p99** — the tail. Where timeouts, retries, and cascading failures originate.
+- **p50** — useful as a health signal, never as a budget.
+
+Two rules that people skip:
+
+- **Fan-out multiplies the tail.** A page making 10 parallel calls to a service with a 1-in-100 slow response has roughly a 1-in-10 chance of hitting one. Your p99 is your caller's p90.
+- **Percentiles do not average.** You cannot mean the p99s of ten instances and get the fleet p99. Aggregate from the underlying distribution, or report per-instance.
+
+Also budget **throughput at a latency** ("p95 under X at N req/s"), not latency alone — latency measured at idle tells you nothing about behavior under load.
+
+## Verdict format
+
+```
+PERF BUDGET CHECK — <scope>
+
+VERDICT: PASS | FAIL | UNMEASURABLE | NO-BUDGETS-DECLARED
+
+Budgets declared in: <file / AGENTS.md / CI step>
+
+  Metric            Budget      Before      After      Source              Verdict
+  <name>            <declared>  <measured>  <measured> <where from>        PASS/FAIL
+  <name>            <declared>  —           —          none                UNMEASURABLE
+
+REGRESSIONS
+  [R1] <metric> — <before> → <after> (<delta>, budget <limit>)
+       Likely cause: <the specific change>
+       Confidence:   🟢 measured both sides, same conditions
+                     🟡 measured, conditions differ
+                     🔴 estimated from the diff, not measured
+
+BUDGETS WITHOUT A SOURCE (n) — these are wishes, not budgets
+  <metric> — declared as <limit>, nothing measures it. Propose: <source>
+
+NOT MEASURED — <what this check could not cover>
+```
+
+Never report PASS for something you did not measure. `🔴 estimated` is honest; a fabricated green is not.
+
+## Proactive Triggers
+
+- **A dependency is added to a client bundle** → estimate its cost and check the route's bundle budget before the diff merges.
+- **A budget is declared with no measurement source** → flag it as a wish; it is providing false assurance right now.
+- **A latency budget is stated as an average or a "typical" number** → flag it; propose p95/p99 and explain what the average hides.
+- **A loop, N+1 query, or per-item network call appears in a request path** → flag it; this is the classic p99 source.
+- **An image, embed, or injected element lands without reserved dimensions** → flag the CLS risk.
+- **A previously lazy-loaded module becomes eagerly imported** → flag it; this is the most common silent LCP and bundle regression.
+- **Synchronous or blocking work is added to an interaction handler** → flag the INP risk.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Does this regress performance?" | Budget table with before/after per metric, verdict, and confidence on each measurement |
+| "Audit our budgets" | Per-budget health: declared / measured / enforced / wishful, with the gaps named |
+| "We have no budgets" | Proposed budget categories and measurement sources, structure only — the team sets the numbers |
+| "Why is p99 bad when p50 is fine?" | Tail analysis: fan-out, contention, cold paths, GC, retries — with where to look |
+| "How big is this dependency really?" | Post-tree-shake cost on the affected entry points, plus what it duplicates |
+
+## Communication
+
+Bottom line first: PASS, FAIL, or UNMEASURABLE. Always name the measurement source next to every number — an unsourced number is not evidence. Tag confidence: 🟢 measured both sides under the same conditions, 🟡 measured with differing conditions, 🔴 estimated from reading the diff. Say "not measured" rather than implying a check happened.
+
+## Related Skills
+
+- **spec-driven**: Use when a spec has non-functional criteria — each must name its measurement source at the spec gate. NOT for correctness criteria.
+- **adr-write**: Use when a budget or a performance trade-off constrains future work — the number belongs in Consequences.
+- **architecture-guard**: Use when a fix adds indirection or a network hop that costs latency. NOT for the measurement itself.
+- **test-first**: Use for correctness tests; performance assertions are budget checks against a measurement source, not unit tests.
+- **security-review**: Use when a mitigation (validation, crypto, extra round-trip) has a measurable latency cost worth budgeting.
+- **onboard**: Use to discover existing budgets and measurement infrastructure in an unfamiliar repo.
+- **handoff**: Use when pausing with a budget knowingly regressed — say so explicitly in Status so nobody merges it by accident.
+- Commands: `/verify` runs the declared measurement, `/review` pairs this with correctness review, `/plan` is where budget impact should first be considered, `/adr` records an accepted regression.

package/registry/skills/perf-budget/references/budget-catalog.md

@@ -0,0 +1,165 @@
+# Budget catalog
+
+Categories worth declaring, what each actually means, how each is measured, and the diff-level signals that a change is about to break one.
+
+**No numbers here.** Limits are declared by the project — in a budgets file, in `AGENTS.md`, or in a CI step that fails. This file tells you *what* to declare and *how* it gets measured, never *how much*.
+
+---
+
+## Web vitals
+
+### LCP — Largest Contentful Paint
+
+**What:** time until the largest above-the-fold element renders. The user's proxy for "did the page load".
+
+**Measured by:** field data from real sessions at a declared percentile (the budget), and lab runs in CI (the early warning). Both, and never confuse the two.
+
+**Declare:** the percentile, the page or page-type, and the device/network class the field data is segmented on.
+
+**Diff signals:**
+- A render-blocking stylesheet or script added to the document head
+- A hero image without dimensions, without a modern format, or without priority hints
+- A font strategy change that delays first paint
+- Above-the-fold content moved from server-rendered to client-rendered
+- A new server call added to the critical rendering path
+- A redirect added before the document response
+
+### INP — Interaction to Next Paint
+
+**What:** responsiveness across all interactions in a session, reported at a high percentile of them. Replaces first-input-only measurement — it catches the slow interaction on the fifth click, which is where real frustration lives.
+
+**Measured by:** field data only for the true budget; lab interaction traces and long-task counts as proxies in CI.
+
+**Declare:** percentile, and which interactions count (all, or a named critical set).
+
+**Diff signals:**
+- Synchronous work added inside an event handler
+- A state change that re-renders a large subtree
+- A large list rendered without virtualization
+- Heavy parsing, sorting, or serialization on the main thread
+- A new third-party script that runs on interaction
+- Work that should be deferred or moved off the main thread
+
+### CLS — Cumulative Layout Shift
+
+**What:** how much content jumps after it is visible. Cheap to keep at zero, embarrassing when broken.
+
+**Measured by:** field data at a percentile; lab runs catch most causes deterministically.
+
+**Diff signals:**
+- Image, video, iframe, or ad slot without reserved dimensions
+- Content injected above existing content (banners, notices, cookie bars)
+- A font swap without metric-compatible fallback sizing
+- Animation of layout-affecting properties instead of transform/opacity
+- Content that appears after data loads without a reserved skeleton
+
+### Supporting metrics (diagnose, do not budget)
+
+TTFB, FCP, total blocking time, long-task count, main-thread time. Budget the vitals; use these to explain a vitals regression.
+
+---
+
+## Bundle size
+
+### Per-entry / per-route transferred size
+
+**What:** compressed bytes over the wire for a given entry point.
+**Measured by:** the build's own size reporting, or a size-limit check in CI that fails the build.
+**Declare:** per entry point or route, not one app-wide total — a global budget lets one route absorb everyone's regressions invisibly.
+
+### Uncompressed parse size
+
+**What:** bytes the engine must parse and compile.
+**Why separately:** compression hides parse cost. On mid-range devices, parse and compile time frequently exceeds download time, and the transferred number says nothing about it.
+
+### Per-dependency cost
+
+**What:** what a single package actually adds after tree-shaking and deduplication.
+**Measured by:** bundle analysis of the built output — before/after, not the package's advertised size.
+
+**Diff signals:**
+- A new runtime dependency in client code
+- A namespace/wildcard import where a named import would tree-shake
+- Locale, icon, or timezone data imported wholesale
+- A second copy of a library at a different version
+- A previously lazy route or module becoming eagerly imported (the most common silent regression)
+- A polyfill added for a browser the project's support matrix does not include
+
+### Asset budgets
+
+Images, fonts, and video totals per page. Declare per page-type, plus format requirements (modern formats, subset fonts) — the format rule prevents most regressions before size checking has to.
+
+---
+
+## Backend latency
+
+### Endpoint latency percentiles
+
+**What:** p95 and p99 server-side duration per endpoint or operation.
+**Measured by:** production telemetry aggregated from the request distribution — never by averaging instance-level percentiles, which is arithmetically invalid.
+**Declare:** per endpoint (or endpoint class), with the percentile and the load condition. "p95 under X at N req/s" is a budget; "usually fast" is not.
+
+**Never declare an average.** A mean of 100ms is consistent with 95% of requests at 40ms and 5% at 1.2s. It hides the affected users, moves on a single outlier, and cannot be aggregated across services.
+
+**Diff signals:**
+- A query added inside a loop (N+1)
+- A synchronous call to another service on a request path
+- A missing index on a new query predicate
+- A query returning unbounded rows — no limit, no pagination
+- A lock, transaction, or shared resource held across an external call
+- Serialization of a large payload added to a hot path
+- A retry added without a cap, jitter, or budget
+
+### Dependency and fan-out latency
+
+**What:** time spent in each downstream call, and how many are made per request.
+**Why:** your p99 is dominated by your dependencies' tails. Ten parallel calls to a service with a 1-in-100 slow response give roughly a 1-in-10 chance of hitting one — **your caller's p90 is your dependency's p99.**
+**Declare:** a per-request fan-out limit alongside the latency budget. Fan-out is the variable people forget to bound.
+
+### Throughput and saturation
+
+**What:** requests per second sustained while still meeting the latency budget; and utilization of the constraining resource (CPU, connection pool, queue depth).
+**Why:** latency measured at idle predicts nothing about behavior at load. Saturation is the leading indicator; latency is the lagging one.
+
+### Background and async work
+
+Queue depth, oldest-message age, and job duration percentiles. A job that quietly takes twice as long is invisible to every request-latency budget until the queue backs up into one.
+
+---
+
+## Database
+
+- **Query duration percentiles** per query shape — p95/p99, from the database's own statistics.
+- **Rows examined per row returned** — the ratio that predicts a scan before it becomes a latency problem.
+- **Connection pool utilization** — saturation here presents as unexplained latency everywhere.
+- **Transaction duration** — long transactions cause lock contention that shows up in unrelated endpoints.
+
+**Diff signals:** a new query without an index on its predicate, a query with no bound, a transaction wrapping a network call, a migration adding a column with a default on a large table.
+
+---
+
+## Build and CI
+
+Legitimate budgets, and the ones most often left undeclared:
+
+- Cold and warm build duration
+- Test suite wall-clock, split by fast and slow sets
+- CI pipeline total time to a merge decision
+
+**Why they matter:** a slow local test run silently kills the test-first loop long before anyone files a ticket about it.
+
+---
+
+## Choosing what to declare
+
+Start with the smallest set that is actually measured. Four enforced budgets beat twenty aspirational ones.
+
+| Project type | Declare first |
+|---|---|
+| Public web app | LCP + INP + CLS at a percentile, plus per-route bundle size |
+| Internal dashboard | INP and bundle size; LCP matters less on a warm, authenticated app |
+| API / service | p95 and p99 per endpoint class, plus fan-out limit |
+| Library | bundle size delta per release, plus a benchmark on the hot path |
+| Data pipeline | per-stage duration percentiles and throughput, not latency |
+
+Each declaration must carry: **metric · limit · percentile or condition · measurement source · enforcement point.** Missing the last two makes it a wish.