Skip to content

majordomus search

Find a durable record without reading all of them, in authority order.

Find a durable record without reading all of them, in authority order.

  • read-only
  • memory
  • active task optional
  • --json

Literal search, not a regular expression. Exits 12 when nothing matches, so a caller can distinguish absence from failure.

Syntax

majordomus search "<text>" [--kind <kind>] [--task <id>] [--limit <n>] [--json]

Lifecycle

  1. Set up
  2. Begin
  3. Work
  4. Verify
  5. Conclude
  6. Inspect

Other commands at this stage:doctor, watch, history, doctrine, version, knowledge, rules, bench.

Reads

  • .ai/local/state/handovers/
  • .ai/local/state/checkpoints/
  • .ai/local/state/decisions.md
  • .ai/local/state/open-questions.md
  • .ai/repo/prompts/
  • .ai/local/state/ledger.jsonl

Writes

Nothing. This command is read-only.

Exit codes

Only the codes this command can produce. The full contract is on the commands index.

  • 0 ok
  • 2 usage
  • 12 missing artifact

Finding a record without reading all of them

A literal search across every durable store, in authority order. It exists so that a worker can find what was already decided instead of deciding it again.

A term that appears in the records

term appears
yes

Given this repository

# An active task that has already produced a checkpoint, a decision and an open question.
. "$FIXTURE_SETUP/active-task.sh"
printf 'the parser now refuses tabs\n' | "$MJ" checkpoint >/dev/null
"$MJ" decision add "refuse tabs in the parser" --why "two encodings for one token" >/dev/null
"$MJ" question add "should tabs be an error or a warning?" >/dev/null

Run

$ majordomus search tabs

Output contains

  • decision
  • match\(es\)

exit 0

Each hit names the kind of record, the file and the line, so the result can be opened rather than merely counted.

A term that appears nowhere

term appears
no

Given this repository

# An active task that has already produced a checkpoint, a decision and an open question.
. "$FIXTURE_SETUP/active-task.sh"
printf 'the parser now refuses tabs\n' | "$MJ" checkpoint >/dev/null
"$MJ" decision add "refuse tabs in the parser" --why "two encodings for one token" >/dev/null
"$MJ" question add "should tabs be an error or a warning?" >/dev/null

Run

$ majordomus search zzzznotfound

Output contains

  • no match

exit 12

Exit 12 rather than 0, so a script can tell absence from failure without parsing the output.

Reference

Find durable records without reading all of them. Read-only.

A literal, case-insensitive, fixed-string search across handovers, checkpoints, decisions, questions, prompt assets and the ledger, in that order — authority order, so the most reliable evidence appears first. --kind restricts it and is repeatable; --task narrows to one task; --limit caps each kind.

Deliberately not an index and not an embedding. The corpus is a handful of Markdown files and one JSONL; a scan is faster than the staleness problem an index would introduce, and "transparent" is worth more here than "clever". Exit 0 with matches, 12 with none.

$ majordomus search "callback" --kind decision --kind checkpoint
checkpoint  .ai/local/state/checkpoints/20260903T194500Z--main--3f2a9c1--8c1d0e4a.md:12  Cause is in callback normalisation, not in the comparison.
decision    .ai/local/state/decisions.md:31  ## 2026-09-03 — Normalise the callback URI before comparing state
search: 2 match(es)

Evidence

Every case below runs in CI on Linux and macOS. The site refuses to build if a public command has no behavioural case, no negative case, or no demonstration.

Behaviour

Failure modes

Implementation

Demonstration

Guarantees this command carries