A snapshot: read at commit 707a04c7ce8 on 2026-10-18T00:06:01Z by majordomus 0.29.0. Nothing on this page is read again. See it live

I0811

Read-only knowledge lookup with an ordering that can be explained

Where it stands

Readiness: complete completion is recorded and every required evidence token is present
Status: DONE
Can start: not now
Milestone: M003
Milestone status: ACTIVE
Wave: 4
Waiting on: none
Holds back: I0812 I0814
Behind it in all: 5
Evidence: 2 of 2

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.
Now: `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.
Wanted: `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.
Done when: unknown: the record declares no `completion`
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.

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_querybash test/run.sh 24_prompt_search
Evidence required: query_explainablereadonly_proven
Evidence present: query_explainablereadonly_proven

Touches: lib/knowledge.shbin/majordomusdocs/CLI.mdtest/cases
Not: Any change to the existing search command's behaviourEmbeddings, similarity, or any opaque scoreRebuilding the index from a read
Depends on: I0809
Priority: p1
Profile: implementation
Parallel safe: false
Owner: unknown: the record declares no `owner`

Adapter: scripts/github-sync
Repository: unknown: the derived plan's header carries no repository
External issue: unknown: a live GitHub state; this executable makes no network call, so only `scripts/github-sync --check` can answer it
State there: unknown: a live GitHub state; this executable makes no network call, so only `scripts/github-sync --check` can answer it

Nothing is wrong with these records.