# docs/caveats/

One entry per known limit: something broken, deferred or unsafe that a session
will otherwise walk into. An entry names what fails, who it costs, and the
condition that makes it worth fixing.

Two things do not belong here. The evidence is a dated file under `docs/evals/`.
The reasoning behind a subsystem is its living doc directly under `docs/`. A
caveat is the pointer between them plus the trigger.

## Rules for this directory

* One file per area, one `##` section per limit, each carrying its task id.
* **A caveat with no revisit trigger is a complaint.** Give it one or delete it.
* Closing a limit deletes its entry. It does not edit it to say "fixed", and it
  never edits the frozen measurement it came from. The durable record of a fix
  is the commit and the subsystem's living doc.
* An entry whose task is closed but whose limit is still live is the failure
  mode to watch for. The id joins the two directions, so check both.

## Index

Every entry below came from the 2026-08-10 deep audit
(`docs/evals/2026-08-10-repo-audit.md`), except the last, which came from wiring
the gate the audit asked for. Five of the twenty findings are fixed and have no
entry. The unauthenticated mavgpud proxy was V-673. The 20 reachable advisories
in the toolchain and `x/text` were V-682. The missing analyzers were V-694, and
what they now report is the baseline entry under V-701. The two unguarded
invariants were V-692 and V-693, and their guards are described in
`docs/routing.md`.

| limit | severity |
| --- | --- |
| [Anyone past the proxy can enroll a passkey](security.md#enrollment) | high |
| [Passkey credentials are rewritten in place](security.md#credentials) | medium |
| [An empty STT transcript reads as a successful one](external-inputs.md#stt) | medium |
| [Open-Meteo's empty body becomes 0°C](external-inputs.md#weather) | medium |
| [Dialogue persistence errors are swallowed](storage.md#dialogue) | medium |
| [The reminder transition is a lost update](storage.md#reminders) | medium |
| [A recall miss scans two whole tables](storage.md#recall) | medium |
| [Closing a TCP listener can strand Accept](transport.md#accept) | medium |
| [PTT reads an unbounded body](transport.md#ptt) | medium |
| [mavweb errors cannot be traced](transport.md#errors) | medium |
| [Fact enrichment is a 20-call serial waterfall](workers.md#enrichment) | medium |
| [A suppressed nudge is phrased anyway](workers.md#nudges) | medium |
| [Committed absolute paths pin the build to this box](config.md#paths) | medium |
| [The env example omits deployed variables](config.md#secrets) | medium |
| [The analyzers pass against a baseline, not zero](dependencies.md#baseline) | medium |
| [Domain packages depend on store and IPC types](layering.md#dtos) | low |
| [Eleven symbols are unreachable](layering.md#deadcode) | low |
