#1080: ✨ Implement build_sqon v2

.dev/docs/atlas/roadmap/mcp-integration-readiness.md

@@ -8,7 +8,7 @@ Six targeted improvements to make Arranger a well-behaved upstream for an MCP se
 
 #### SQON generation via `build_sqon` tool [done]
 
-_Shipped 2026-08-10 (#1080), version 1: the scalar operators (`in`, `not-in`, `gt`, `gte`, `lt`, `lte`, `between`) with one `and`/`or` combination per call. Text operators and mixed AND/OR nesting are deliberately deferred; see § Phasing in `.dev/docs/build-sqon-tool.md` for the v2/v3 shape. The design and implementation records are `.dev/docs/build-sqon-tool.md` and `.dev/docs/build-sqon-implementation.md`._
+_Shipped 2026-08-10 (#1080), version 1: the scalar operators (`in`, `not-in`, `gt`, `gte`, `lt`, `lte`, `between`) with one `and`/`or` combination per call. **Version 2 shipped 2026-08-25**, adding `wildcard` text search via `fieldNames` plus `some-not-in` and `all`, which brings the tool to full parity with `modules/sqon` except for the unimplemented `fuzzy`. Still deferred: mixed AND/OR nesting (v3) and `fuzzy` (v2.1, blocked on three things listed in § Phasing). The design and implementation records are `.dev/docs/build-sqon-tool.md` and `.dev/docs/build-sqon-implementation.md`._
 
 _Priority when open: high. Somewhat urgent: MCP SQON generation was hit-or-miss in practice._
 
@@ -20,11 +20,11 @@ This is also more token-efficient than the alternatives: embedding SQON document
 
 **Scope, as built:**
 
-1. **`build_sqon` tool** in `apps/mcp-server/src/mcp/buildSqonTool.ts`, registered from `mcp/tools.ts`: accepts a `catalogueId`, one `combination` (`and`/`or`), a list of `clauses` (`fieldName`, `operator`, `value`, optional `negate`), and an optional `existingSqon`; validates every clause against that catalogue's introspection; folds them with `addFilterClause`; returns the SQON with a plain-English `summary`, a submitted-versus-final clause count, and a note when the two differ. One call carries the whole batch: the originally-scoped one-clause-per-call shape was rejected during design, because a per-clause call turns an N-condition query into N round trips and makes a rejected clause N/2 calls of wasted work on average (see § Why one call builds a whole batch in `.dev/docs/build-sqon-tool.md`).
+1. **`build_sqon` tool** in `apps/mcp-server/src/mcp/buildSqonTool.ts`, registered from `mcp/tools.ts`: accepts a `catalogueId`, one `combination` (`and`/`or`), a list of `clauses` (`fieldName` or, for `wildcard`, `fieldNames`; plus `operator`, `value`, optional `negate`), and an optional `existingSqon`; validates every clause against that catalogue's introspection; folds them with `addFilterClause`; returns the SQON with a plain-English `summary`, a submitted-versus-final clause count, and a note when the two differ. One call carries the whole batch: the originally-scoped one-clause-per-call shape was rejected during design, because a per-clause call turns an N-condition query into N round trips and makes a rejected clause N/2 calls of wasted work on average (see § Why one call builds a whole batch in `.dev/docs/build-sqon-tool.md`).
 2. **Agent-optimized tool description** [done]: the operator descriptions are generated at module load from `getSqonFieldOperatorDetails()`, so they cannot drift from `modules/sqon`, and are attached per schema branch rather than once for all operators, which keeps the emitted JSON Schema roughly a third smaller than repeating the full list on every branch. The batch-level guidance sits on the `clauses` array, once.
-3. **Versioned changelog** [not done]: the tool interface is not versioned and carries no machine-readable changelog. Version 1's operator coverage is described in the tool's own input schema, which is authoritative but not versioned. Revisit if and when a v2 changes the input shape rather than only extending it.
+3. **Versioned changelog** [not done]: the tool interface is not versioned and carries no machine-readable changelog. Operator coverage is described in the tool's own input schema, which is authoritative but not versioned. v2 only extended the input shape (a fourth and fifth union branch, and one more operator on an existing branch), so this stayed unnecessary; revisit if a later version changes an existing branch rather than adding one.
 
-**Prerequisite (resolved):** the `build_sqon` tool's operator coverage is bounded by `SqonBuilder`'s. This was previously blocked on absorbing full operator coverage into `modules/sqon`; that absorption is now complete (see [Deprecate `sqon-builder`](#deprecate-sqon-builder)) and `modules/sqon`'s `SqonBuilder` already covers `all`, `between`, `gte`, `in`, `lte`, `not-in`, `some-not-in`, and `wildcard`. `build_sqon` can ship with full operator coverage from the start; no partial-coverage phasing is needed.
+**Prerequisite (resolved):** the `build_sqon` tool's operator coverage is bounded by `SqonBuilder`'s. This was previously blocked on absorbing full operator coverage into `modules/sqon`; that absorption is now complete (see [Deprecate `sqon-builder`](#deprecate-sqon-builder)) and `modules/sqon`'s `SqonBuilder` already covers `all`, `between`, `gte`, `in`, `lte`, `not-in`, `some-not-in`, and `wildcard`. In the event v1 did phase anyway, for reasons of MCP-surface design rather than builder coverage: `fieldNames` is a second clause shape, not just another operator, and it was cleaner to ship the single-field shape first. v2 closed the gap on 2026-08-25. `fuzzy` is the one operator still outstanding, and it is outstanding in `modules/sqon` too.
 
 **Considered and deferred: TOON as output format.** [TOON (Token-Oriented Object Notation)](https://toonformat.dev) was evaluated as an optional compact output format, both for MCP responses (field listings, search results) and as a potential evolution of the SQON surface syntax itself. The MCP response case has genuine merit: TOON's tabular collapse applies well to uniform arrays like field listings. The SQON syntax case is weaker: SQON's recursive tree structure limits the tabular gains, and the `build_sqon` tool already removes the LLM from the synthesis loop, which was the main pain point. Revisit as an enhancement once the `execute_query` MCP implementation is available and real token budgets can be measured empirically.
 
@@ -73,7 +73,7 @@ _Priority: medium. Recurring gap logged as a session open thread many times over
 **Scope:**
 
 - A dedicated `docs/reference/` page (or an extension of `mcp-server.md`) covering the full MCP tool surface: what each tool does, its input/output shape, and the elicitation-confirmation flow in `execute_query`.
-- ~~To check once `build_sqon` ships: `docs/concepts.md`'s `fieldName`/`fieldNames` definition~~ done 2026-08-10: the definition now covers both positions, the `content` object and a flat clause-building argument, and the vocabulary table entry matches.
+- ~~To check once `build_sqon` ships: `docs/concepts.md`'s `fieldName`/`fieldNames` definition~~ closed 2026-08-25, deliberately without adding the MCP usage. `concepts.md` is general Arranger vocabulary rather than an MCP page, so neither the prose definition nor the vocabulary table mentions `build_sqon`; the tool's flat `fieldName`/`fieldNames` arguments are documented in `docs/mcp-server.md` instead, and they carry the same names precisely so no second definition is needed. Both entries did change on that date to stop describing `fuzzy` as an existing operator.
 
 _Coordinate with whichever MCP work lands next; `execute_query` shipped in #1077 and `build_sqon` in #1080, both now named in `docs/mcp-server.md`._