📝 Record the autocomplete and matcher-design decisions

The matcher is now two three-overload factories; library.md documents why
the union merge, inferred universe, conditional RequireKeys and cases-first
paths were rejected, and lists the two open issues (the fallback sees all of
T; a redundant _ is still accepted). testing.md records the language server
as the autocomplete oracle, and CONTRIBUTING points the exception at the
matcher's own test file.

The backlog marks the design-doc and autocomplete groundwork done alongside
the adoption.

development/testing.md

@@ -30,7 +30,8 @@ before the implementation.
 - Testing the type only: it would not catch handler dispatch or the `_`
   fallback (see `src/primitive.test.ts`).
 
-The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
+The runner is `node --test --strip-types` over `src/**/*.test.ts` and
+`scripts/**/*.test.ts`; the tiers are in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
 `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
 build step, and the runner relies on the `.ts` import-extension convention (see
@@ -96,6 +97,10 @@ import { LspSession } from "#test-utils/lsp-completion.ts";
 - The helper uses `node:` builtins (it drives a language server), so
   `import/no-nodejs-modules` is off for `src/util/__tests__/**` in
   `.oxlintrc.json` — the same exception the old `scripts/**` scope carried.
+- Helpers carry no library coupling: their tests probe in-memory documents
+  whose contextual types are written inline, so only the helper's own contract
+  (marker handling, position, label extraction) is under test. A test that
+  asserts a _matcher's_ popup belongs with the matcher.
 
 #### Rejected
 
@@ -111,11 +116,59 @@ import { LspSession } from "#test-utils/lsp-completion.ts";
   still guards non-test helpers importing each other, and the exemption is
   only needed for the one specifier the mapping already solves cleanly.
 
+## Autocomplete
+
+#### Decision (2026-09)
+
+Completion is verified by driving the repo's own language server
+(`tsc --lsp --stdio`, the same server pi's LSP extension talks to) through
+the test helper `#test-utils/lsp-completion.ts`
+(`src/util/__tests__/lsp-completion.ts`), not through the type system:
+
+```sh
+node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
+```
+
+The script prints the labels the server offers at a `/*COMPLETE*/` marker inside
+`<file>` (the marker is stripped before the document is sent). Its `LspSession`
+is imported by `src/util/__tests__/lsp-completion.test.ts` — which tests the
+helper itself against inline documents, never the library's code — and by
+`src/primitive.test.ts`, where the same probe asserts the matcher's popup;
+the CLI is for manual inspection.
+
+#### Why
+
+- Completion is a contextual-type property: it depends on which overload
+  signature TypeScript picks for the object literal, and no type-level assertion
+  observes that.
+- `Parameters<typeof factory>[0]` resolves only the _last_ overload, so it is
+  not the popup's contextual type either — see
+  [library.md § Matcher shape](./library.md#matcher-shape).
+- The server is the only ground truth; the script reproduces what the editor
+  shows.
+
+#### Rejected
+
+- **`expect-type` would not work**: there is no operator for “the popup offers
+  these labels”. `toExtend` / `toEqualTypeOf` test assignability and cannot say
+  which overload supplied the contextual type.
+- **Checking by hand in the editor**: not reproducible in review or by an agent.
+- **`@ts-expect-error` at a completion position**: it asserts the absence of a
+  compile error, not the presence of specific labels.
+
+#### Known issue
+
+- Each test spawns its own `tsc` server so the tests share no state and pass in
+  any order; the file is an integration test (~1.6 s) that needs `node_modules`.
+  `didOpen` is handled in order before the completion request, so no settle
+  delay is needed.
+- The server answers some requests with a string id (`client/registerCapability`);
+  the client must tolerate `string | number` ids or the server stalls.
+
 ## Known issues
 
 - The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
-  test files that use it (`src/primitive.test.ts`) carry a
-  file-level `oxlint-disable
-typescript/no-floating-promises` with an explanatory comment. It is a known
-  false positive, not a rule worth disabling project-wide (see
+  test files that use it (`src/primitive.test.ts`) carry a file-level
+  `oxlint-disable typescript/no-floating-promises` with an explanatory comment.
+  It is a known false positive, not a rule worth disabling project-wide (see
   [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).