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

BLOCKED wave 5 · 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/69_knowledge_query.sh

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

• I0810READY A content-hash manifest that makes a second sync cheap

What waits on this

• I0812BLOCKED Validate the graph, and let doctor and watch ask the same validator
• I0814BLOCKED 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

None recorded. Every token above needs a command or an artifact behind it before this issue can be completed; narrative is refused.

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

—

verified

—

completed

—

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.