feat: the query surface — doc query + MCP query tool (ADR-0023, stacked on #112)

[HenryCFnord]

Stacked on #112 (retarget to main after it merges; independent of #113–#116 — the query matches predicate strings and needs no vocabulary machinery). Draft until the base lands. This closes D7, the last open design point of the knowledge-repository program.

The owner's decisions: structured conjunctive filters instead of a query language, doc query at the store, the MCP query tool in the same slice.

What this is

The P8 ask — "find all Concepts where conformsTo: ISO19115, so agents navigate without prompting" — as one primitive:

arqix doc query --kind entity --lifecycle draft --edge exact-match=dcat:* --format json

• Filters are conjunctive: kind, lifecycle, repeatable edge patterns; a document matches when every filter holds.
• An edge pattern is predicate=target: bare arqix property name or full IRI; a trailing * on the target matches as a prefix. Malformed patterns are usage errors (exit 2).
• The result is the catalog shape plus each document's matching edges, versioned (schema_version), deterministic.
• The MCP query tool joins search/read/list, backed by the same store function — the transport-separation contract (REQ-05-01-12-03) extends unchanged.
• Deliberately absent (recorded in ADR-0023): disjunction, negation, multi-hop traversal — each returns as a filter-set extension when a real corpus question needs it, never as a language.

The load-bearing detail

Edge matching reads the declared triples from the raw frontmatter lines (declared_edges), not from Document.triples — the shared parser's triple extraction is arqix-scoped by its oracle-era contract, so external targets (dcat:Dataset, the whole crosswalk case) would be invisible through it. Same seam as the crosswalk unit in #116, same rationale, documented in place.

Commit order (spec-first)

1. docs: ADR-0023 + chapter-9 row.
2. spec: REQ-02-01-06-04 on US-02-01-06 (find-and-read) and REQ-05-01-12-04 on US-05-01-12 (MCP) — goals-not-features, no new story.
3. red: two tests, verbatim evidence:

doc_query_filters_documents_by_structured_filters ... FAILED  (unrecognized subcommand 'query')
mcp_query_tool_answers_like_the_cli ... FAILED  (no query tool in the catalog)

4. feat (green): declared_edges + query_json + store::query, the DocCommand::Query surface, the MCP tool (catalog entry + dispatch).
5. docs: the doc query wire schema in the ICD, program status and roadmap (D7 landed).

Validation

Both tests green (cli_mcp: 7 passed); full just ci green before every commit (unpiped log, exit 0). Conjunction is pinned by the test (adding a non-matching lifecycle empties the result), as is the prefix match and the usage-error leg.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gie4jfrHKCxQktD2UsvH4Q

---

Generated by Claude Code