muse log/rev-list have no commit-message search (--grep) — agent-guide.md documents a nonexistent 'muse query' command

muse log/muse rev-list have no commit-message search — and the ecosystem agent-guide documents a muse query command that doesn't exist

How this was found

While investigating musehub#225 (IdentityGraphService/QuorumEngine dead-code audit), I needed the git-muscle-memory equivalent of git log --grep to search commit messages for "QuorumEngine". I reached for what ~/ecosystem/muse/docs/agent-guide.md documents:

muse code query "message =~ 'QuorumEngine'" --json

This failed:

❌  Unexpected character at position 0: 'm'

Root cause — two separate, compounding doc/CLI gaps

1. muse code query is a symbol-graph structure query, not a commit-message search, and its real grammar doesn't match what I guessed:

$ muse code query --help
...
Supported operators:  =  ~=  ^=  $=  !=        (NOT =~)
Supported keys: kind, language, name, qualified_name, file, hash,
                body_hash, signature_id, lineno_gt, lineno_lt,
                size_gt, size_lt                (NO "message" key at all)

code query answers "which symbols have this shape" (kind=function, name~=validate, etc.) — it has no concept of commit messages whatsoever. I was holding it wrong, but the agent-guide's own trigger-table entry encourages exactly this mistake:

| Query commit history by predicate | `muse code query "symbol == 'X'" --json` |

— wrong operator (== isn't valid; real ops are =/~=/^=/$=/!=), wrong key (symbol isn't a supported key), and wrong command entirely (code query is symbol-graph, not commit-history).

2. Separately, agent-guide.md's "Core commands" table documents a bare top-level command that doesn't exist in the installed CLI at all:

| Query commit history with predicates | `muse query "author == 'gabriel'" --json` |

$ muse query "author == 'gabriel'" --json
muse: error: argument COMMAND: invalid choice: 'query' (choose from
help, agent, agent-config, annotate, apply, ... [full subcommand list,
no "query" anywhere])

The actual gap underneath both doc bugs: there is genuinely no way to search commit messages by content in the muse CLI today. The closest existing primitives are:

• muse log --author/--since/--until/--section/--track/--emotion — filters by metadata fields, not message content.
• muse rev-list --author PATTERN --after DATE --before DATE --touches PATH — same category, no message-content filter.
• muse content-grep — searches file content at a ref, not commit messages.

None of these answer "which commits mention X in their message" — the single most common git log --grep use case (finding the commit that introduced/touched a feature by searching its message for an issue number, a keyword, a symbol name). I ended up manually piping muse log --json -n 2000 into a Python loop checking "quorum" in m.lower() — functional, but exactly the kind of thing a CLI flag should do natively, and exactly the git muscle-memory gap this workspace's agent-guide.md Gitism Glossary section is meant to catch and close.

Scope — multi-phase TDD plan

Phase 0 — Audit (done, see above)

• Confirmed muse code query has no message-search capability and a different grammar than the agent-guide's own example uses.
• Confirmed bare muse query does not exist as a CLI subcommand at all.
• Confirmed no --grep/message-content flag exists on log or rev-list.

Phase 1 — Design decision

Add --grep <pattern> to both muse log and muse rev-list, matching git's semantics: case-insensitive substring/regex search against the commit message, composable with existing filters (--author, --since, --touches, etc. — AND semantics, matching how --author+--since already compose). Mirrors the existing flag-based filter pattern already used by both commands rather than introducing a whole new predicate-DSL command (code query's v2 grammar is a heavier mechanism built for the symbol graph; commit-history filtering doesn't need that weight — it needs parity with the two or three git flags agents reach for reflexively).

Needs a decision, not an assumption: substring-only vs. full regex support for --grep. Git supports POSIX extended regex by default (git log --grep uses ERE unless --fixed-strings is passed). Recommend matching: --grep takes a Python re pattern (consistent with this codebase's existing content-grep ERE convention — see agent-guide.md's "regex gotchas" section), case-insensitive by default, with the same escaping caveats already documented for content-grep.

Phase 2 — RED tests (write first)

• tests/test_log_grep.py (new): commits with distinct messages; assert muse log --grep <pattern> returns only matching commits; case-insensitive match; regex metacharacter behavior matches content-grep's documented ERE semantics; composes correctly with --author/--since (AND, not OR); empty result set (no matches) returns cleanly, not an error; --json output shape unchanged except for the filtered commit list.
• tests/test_rev_list_grep.py (new): same coverage for rev-list --grep, plus interaction with A..B range syntax and --count.
• Confirm genuine RED (flag doesn't exist yet, argparse rejects it).

Phase 3 — Implement

• Add --grep to both commands' argparse definitions and filtering logic.
• Reuse/extract shared regex-compilation logic if log and rev-list already share a filter-predicate module (audit before duplicating).

Phase 4 — GREEN + regression

• Confirm new tests pass.
• Run full log/rev-list test suites to confirm no regression in existing filter composition (--author, --since, --touches, etc.).

Phase 5 — Fix the documentation bugs that caused this investigation

• Remove the nonexistent bare muse query "author == 'gabriel'" --json entry from agent-guide.md's "Core commands" table; replace with the real muse log --grep/muse rev-list --grep commands once they exist.
• Fix the muse code query "symbol == 'X'" --json trigger-table entry — wrong operator, wrong key, and arguably the wrong command for "query commit history" (that row's intent is commit-history search, which code query can never do — redirect that row to log --grep instead, and keep code query's own correct-syntax entries elsewhere in the Gitism Glossary for symbol-graph queries specifically).
• Add a Gitism Glossary entry for git log --grep → muse log --grep parity, since this is exactly the kind of git-reflex trap the glossary exists to catch.

Phase 6 — Ship

Standard branch/commit/merge/push cycle (feat/<n>-log-grep-message-search), dev → main, push to local/staging/production. Close with a comment documenting the RED→GREEN process and the specific doc corrections made.

Acceptance criteria

• muse log --grep <pattern> and muse rev-list --grep <pattern> exist, are tested, and match commit messages case-insensitively with ERE regex support consistent with content-grep.
• agent-guide.md no longer references the nonexistent bare muse query command, and muse code query's documented example uses real operators/keys from its own --help grammar.
• A fresh agent hitting this exact scenario again (searching commit messages for a keyword) finds a working, documented command on the first try.