I0811 — Read-only knowledge lookup with an ordering that can be explained
Implement `knowledge search`, `knowledge show` and `knowledge related`: deterministic lookup over the generated index with a documented, tested match order, JSON output that names the field each result matched on, and no write of any kind.
DONE wave 4 · p1 · implementation profile · runs alone
Part of M003 — A session is a durable envelope, and knowledge is compiled from what is already canonical.
Objective
Implement `knowledge search`, `knowledge show` and `knowledge related`: deterministic lookup over the generated index with a documented, tested match order, JSON output that names the field each result matched on, and no write of any kind.
Why
A query that rebuilds the index mutates the repository as a side effect of asking a question, which makes a read-only command a write and breaks every reproduce line that follows it. And a relevance order nobody can explain is one nobody can debug; the order has to be a rule, not a score.
Current state
`majordomus search` is a literal grep over the six operational record kinds and must keep that contract unchanged. Nothing searches the repository's canonical artifacts.
Desired state
`knowledge search` ranks by an explicit ladder — exact canonical id, exact title, title prefix, path, tag, then literal body match — and reports the matched field for every result. `knowledge show` prints one node with its source path and hash. `knowledge related` prints the edges into and out of one node with their provenance. A stale index is reported, never silently rebuilt.
Scope
- lib/knowledge.sh
- bin/majordomus
- docs/CLI.md
- test/cases
Out of scope
- Any change to the existing search command's behaviour
- Embeddings, similarity, or any opaque score
- Rebuilding the index from a read
Dependencies
What waits on this
- I0812DONE Validate the graph, and let doctor and watch ask the same validator
- I0814DONE Give the worker a bounded slice of knowledge, not the knowledge base
Acceptance criteria
- The match ladder is documented and a case asserts the order for a query that matches at two levels
- JSON output carries the id, kind, title, source and matched field of every result
- Running every read-only knowledge command leaves git status byte-identical
- A stale index is reported as stale by every read command, and none of them rebuilds it
- The existing search command's output and exit codes are unchanged, proved by its own case still passing
Validation
- bash test/run.sh 69_knowledge_query
- bash test/run.sh 24_prompt_search
Evidence required
- query_explainable
- readonly_proven
Evidence
| covers | type | command | result | at commit |
|---|---|---|---|---|
| query_explainable | test | test/run.sh 3037_a_knowledge_lookup_explains_its_order | ok at feature/a-knowledge-lookup-explains-its-order on master 97c4521f91 (2026-10-14 20:0xZ): knowledge search states its ladder [id, title, title-prefix, path, body] in --json, returns four fixture nodes in that order each with matched and rung, places a query that matches one node at two levels (its exact id, and the body of documents naming it) on the id rung once, and answers the same question twice byte-identically; every result carries id, kind, title, source and matched. Documented in docs/CLI.md under majordomus knowledge. | 97c4521 |
| readonly_proven | test | test/run.sh 3037_a_knowledge_lookup_explains_its_order 24_prompt_search 64_knowledge_discovery 15_command_surface | 4 ok at master 97c4521f91 plus this change (2026-10-14 20:0xZ). Case 3037 runs search, show and related and asserts the working tree's porcelain status is the same after them as before; there is no stored index to go stale, since each call compiles from the version-control index as knowledge nodes does, so none of them rebuilds or writes anything. show and related exit 12 for an unknown id and search exits 2 with no query. Case 24 (the existing search command) still passes unchanged; 15 holds the command surface with search/show/related declared read-only in share/commands.yaml. | 97c4521 |
Risk
Two commands now contain the word search with different corpora and different contracts. If the distinction is not stated where a worker reads it, the wrong one gets used and the answer looks like an absence.
Timeline
- started
- 2026-10-14T20:17:07Z
- verified
- 2026-10-14T20:18:06Z
- completed
- 2026-10-14T20:18:28Z
Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.
Canonical record: .ai/repo/project/issues/I0811.yaml. Read it back with majordomus plan show I0811.