feat(cli): complete code and evidence facades (#390)

Co-authored-by: Codex <codex@openai.com>

Author: solomonneas

QUICKSTART.md

@@ -194,10 +194,14 @@ Capture against an id you actually have: a skill you followed, a memory card (`-
 ```bash
 # optional stations (fail-open everywhere if absent)
 brigade add graphtrail          # or: cargo install graphtrail
-graphtrail sync                 # builds .graphtrail/graphtrail.db in the repo
+brigade code sync .             # explicitly runs local GraphTrail and builds .graphtrail/graphtrail.db
+brigade code context "auth receipt flow"
+brigade code impact brigade.work.verify.run
 brigade add evidence            # miseledger (process-boundary Go binary)
 
-# evidence station CLI (install / plan / health; does not crawl for you)
+# evidence station CLI: explicit local operations
+brigade evidence crawl sessions
+brigade evidence search "auth receipt flow"
 brigade evidence crawl plan     # review-only miseledger init + crawl commands
 brigade evidence doctor
 brigade evidence export plan    # review-only receipts export path
@@ -236,7 +240,11 @@ brigade pantry expiry-alert --send
 ```bash
 # GraphTrail code-graph + optional local semantic search
 brigade add search              # or: brigade add graphtrail
-brigade search sync plan        # review-only; does not run sync
+brigade code sync .             # preferred GraphTrail facade
+brigade code context "auth receipt flow"
+brigade code impact brigade.work.verify.run
+# `brigade search sync|context|impact` remain compatibility aliases.
+brigade search sync plan        # review-only; does not run GraphTrail
 brigade search doctor
 
 # Token Glace (output compaction; TokenJuice was the old name) + optional usage export

docs/command-inventory.md

@@ -19,12 +19,13 @@ enabled: run `brigade extras on` once, or set `BRIGADE_EXTRAS=1`.
 - `brigade budgets` (extras): 2 command path(s)
 - `brigade center` (extras): 29 command path(s)
 - `brigade chat` (extras): 7 command path(s)
+- `brigade code`: 3 command path(s)
 - `brigade completions`: 1 command path(s)
 - `brigade context` (extras): 8 command path(s)
 - `brigade daily`: 26 command path(s)
 - `brigade doctor`: 1 command path(s)
 - `brigade dogfood` (extras): 1 command path(s)
-- `brigade evidence`: 4 command path(s)
+- `brigade evidence`: 6 command path(s)
 - `brigade extras`: 3 command path(s)
 - `brigade friction` (extras): 3 command path(s)
 - `brigade guard`: 1 command path(s)
@@ -57,7 +58,7 @@ enabled: run `brigade extras on` once, or set `BRIGADE_EXTRAS=1`.
 - `brigade runbook` (extras): 5 command path(s)
 - `brigade runs`: 8 command path(s)
 - `brigade scrub`: 1 command path(s)
-- `brigade search`: 3 command path(s)
+- `brigade search`: 6 command path(s)
 - `brigade security`: 15 command path(s)
 - `brigade setup`: 1 command path(s)
 - `brigade skills`: 29 command path(s)
@@ -111,6 +112,9 @@ enabled: run `brigade extras on` once, or set `BRIGADE_EXTRAS=1`.
 - `brigade chat sweep import-issues` (extras)
 - `brigade chat sweep ingest` (extras)
 - `brigade chat sweep validate` (extras)
+- `brigade code context`
+- `brigade code impact`
+- `brigade code sync`
 - `brigade completions`
 - `brigade context archive` (extras)
 - `brigade context build` (extras)
@@ -148,9 +152,11 @@ enabled: run `brigade extras on` once, or set `BRIGADE_EXTRAS=1`.
 - `brigade daily unblock`
 - `brigade doctor`
 - `brigade dogfood` (extras)
+- `brigade evidence crawl`
 - `brigade evidence crawl plan`
 - `brigade evidence doctor`
 - `brigade evidence export plan`
+- `brigade evidence search`
 - `brigade evidence status`
 - `brigade extras off`
 - `brigade extras on`
@@ -416,8 +422,11 @@ enabled: run `brigade extras on` once, or set `BRIGADE_EXTRAS=1`.
 - `brigade runs steer`
 - `brigade runs watch`
 - `brigade scrub`
+- `brigade search context`
 - `brigade search doctor`
+- `brigade search impact`
 - `brigade search status`
+- `brigade search sync`
 - `brigade search sync plan`
 - `brigade security closeout`
 - `brigade security config`

docs/overview.md

@@ -343,9 +343,10 @@ Safety and operations tools:
 Evidence ledger tools:
 
 - [MiseLedger](https://github.com/escoffier-labs/miseledger): local-first evidence ledger. One binary crawls sessions, files, git history, and chat sources (`miseledger crawl ...`), stores `miseledger.adapter.v1` JSONL in SQLite with FTS5, and emits Brigade-ready evidence bundles. No separate exporter install.
-- Brigade station CLI (process boundary; does not crawl for you):
+- Brigade station CLI (process boundary):
   - `brigade add evidence` installs miseledger and prints the crawl/export path
   - `brigade evidence status` / `doctor` — advisory health + next commands
+  - `brigade evidence crawl <args...>` / `search <args...>` - transparent MiseLedger execution; engine output and exit code pass through
   - `brigade evidence crawl plan` / `export plan` — review-only plans under `.brigade/evidence/plans/`
   - `brigade receipts export miseledger --new-only --import` — export verify/run receipts into the ledger
 - Historical note only: StationTrail and SourceHarvest were absorbed into MiseLedger crawl in v0.3.0; their archived repos are migration notes, not active products.

docs/station-contract.md

@@ -18,7 +18,7 @@ Fresh repo installs use the `repo` profile: core, skills, memory, guard, securit
 | `memory` | bootstrap-doctor (optional); memory maintenance is built in | `brigade memory status|lint|compact` plus memory-care for card freshness |
 | `pantry` | agentpantry (Go sidecar) | plans and health-checks sealed browser-session sync; never starts source/sink |
 | `search` | code-search, graphtrail | local semantic search plus a code-graph CLI for callers, impact, and structural diffs |
-| `evidence` | miseledger (Go sidecar) | plans crawl/export and health-checks the local evidence ledger; does not crawl for you |
+| `evidence` | miseledger (Go sidecar) | explicitly runs local MiseLedger for `brigade evidence crawl|search`; crawl/export plans are review-only, and Brigade neither starts daemons nor uploads data |
 
 ## Inspecting a station before install
 

docs/technical-guide.md

@@ -1360,8 +1360,9 @@ First-class station CLIs (always registered; not extras-gated):
 
 | Command group | Plans / health |
 |---|---|
-| `brigade evidence` | `status`, `doctor`, `crawl plan`, `export plan` |
-| `brigade search` | `status`, `doctor`, `sync plan` |
+| `brigade evidence` | `status`, `doctor`, `crawl`, `search`, `crawl plan`, `export plan` |
+| `brigade code` | `sync`, `context`, `impact` |
+| `brigade search` | `status`, `doctor`, `sync`, `context`, `impact`, `sync plan` |
 | `brigade tokens` | `status`, `doctor`, `wire plan` |
 | `brigade stations` | `list`, `discover` |
 
@@ -1377,11 +1378,9 @@ These plan commands do not generate or copy PSKs, start services, or mutate brow
 
 `evidence` (alias `ledger`) is the local evidence-ledger station. MiseLedger remains a process-boundary Go binary; Brigade never imports it.
 `brigade add evidence` installs miseledger and prints the crawl/export path.
-Use `brigade evidence status` and `brigade evidence doctor` for advisory health with explicit `next` commands, `brigade evidence crawl plan` to preview miseledger init/crawl/doctor commands, and `brigade evidence export plan` to preview `brigade receipts export miseledger --new-only --import`.
-These plan commands do not execute crawl or import. Product page: https://brigade.tools/miseledger.
+Use `brigade evidence status` and `brigade evidence doctor` for advisory health with explicit `next` commands. `brigade evidence crawl <args...>` and `brigade evidence search <args...>` relay a safe argv list to MiseLedger, preserving its text or JSON output and exit status. `--code-reference <brigade.code-reference.v1 JSON>` is passed to MiseLedger unchanged, so its exact code-reference lookup runs before lexical fallback. Crawl defaults to 900 seconds and can be changed with the positive finite numeric `BRIGADE_EVIDENCE_CRAWL_TIMEOUT_SECONDS`; search remains at 30 seconds. An invalid crawl timeout reports a diagnostic and exits 2 before starting MiseLedger. `brigade evidence crawl plan` still previews miseledger init/crawl/doctor commands, and `brigade evidence export plan` still previews `brigade receipts export miseledger --new-only --import`. Product page: https://brigade.tools/miseledger.
 
-`search` (alias `code-search`) wires GraphTrail and optional code-search-api. The `code-search-mcp` compatibility key points to the bridge maintained under `code-search-api/mcp`.
-Use `brigade search status` / `doctor` and review-only `brigade search sync plan`. Brigade does not run `graphtrail sync` or start the search API for you.
+`code` runs GraphTrail through a process boundary: `brigade code sync|context|impact <args...>` uses safe argument forwarding and preserves engine text, JSON, and exit status. Sync defaults to 900 seconds and can be changed with the positive finite numeric `BRIGADE_CODE_SYNC_TIMEOUT_SECONDS`; context and impact remain at 30 seconds. An invalid sync timeout reports a diagnostic and exits 2 before starting GraphTrail. `search` retains its `status`, `doctor`, and `sync plan` surfaces; its executable `sync`, `context`, and `impact` forms are compatibility aliases for `code` for at least two minor releases or 90 days, whichever is longer. `search` still wires optional code-search-api, and the `code-search-mcp` compatibility key points to the bridge maintained under `code-search-api/mcp`.
 
 `tokens` wires Token Glace (current name; TokenJuice is the old name) and optional usage-tracker spend export.
 Use `brigade tokens status` / `doctor` and review-only `brigade tokens wire plan`.
@@ -1390,8 +1389,7 @@ Use `brigade tokens status` / `doctor` and review-only `brigade tokens wire plan
 
 `evidence` (alias `ledger`) is the local evidence-ledger station. MiseLedger remains a process-boundary Go binary; Brigade never imports it.
 `brigade add evidence` installs miseledger and prints the crawl/export path.
-Use `brigade evidence status` and `brigade evidence doctor` for advisory health with explicit `next` commands, `brigade evidence crawl plan` to preview miseledger init/crawl/doctor commands, and `brigade evidence export plan` to preview `brigade receipts export miseledger --new-only --import`.
-These plan commands do not execute crawl or import. Product page: https://brigade.tools/miseledger.
+Use `brigade evidence status` and `brigade evidence doctor` for advisory health with explicit `next` commands. `brigade evidence crawl <args...>` and `brigade evidence search <args...>` relay a safe argv list to MiseLedger, preserving its text or JSON output and exit status. `brigade evidence crawl plan` still previews miseledger init/crawl/doctor commands, and `brigade evidence export plan` still previews `brigade receipts export miseledger --new-only --import`. Product page: https://brigade.tools/miseledger.
 
 Security commands:
 

engines/evidence-ledger/internal/app/app.go

@@ -1541,20 +1541,20 @@ func cmdSearch(args []string, out, errw io.Writer) int {
 	if err != nil {
 		return fatalf(errw, "search: %s", err)
 	}
-	if len(rest) < 1 {
-		return fatalf(errw, "usage: miseledger search <query>")
-	}
 	limit := 20
 	if values["limit"] != "" {
 		if _, err := fmt.Sscan(values["limit"], &limit); err != nil {
 			return fatalf(errw, "search: invalid --limit")
 		}
 	}
-	query := strings.Join(rest, " ")
 	codeReference, err := parseCodeReference(values["code-reference"])
 	if err != nil {
 		return fatalf(errw, "search: %s", err)
 	}
+	if len(rest) < 1 && codeReference == nil {
+		return fatalf(errw, "usage: miseledger search <query>")
+	}
+	query := strings.Join(rest, " ")
 	db, _, err := openMigrated()
 	if err != nil {
 		return fatalf(errw, "search: %s", err)
@@ -1907,6 +1907,9 @@ func search(db *sql.DB, opts SearchOpts) ([]SearchResult, error) {
 		if len(exact) != 0 {
 			return exact, nil
 		}
+		if opts.Query == "" {
+			return exact, nil
+		}
 	}
 	sqlText, params := buildSearchQuery(opts)
 	rows, err := db.Query(sqlText, params...)

engines/evidence-ledger/internal/app/app_test.go

@@ -2082,6 +2082,67 @@ func TestSearchUsesExactCodeReferenceBeforeLexicalFallbackAndLegacyItemsStillSea
 	}
 }
 
+func TestCLISearchAllowsOnlyValidExactCodeReferenceWithoutLexicalQuery(t *testing.T) {
+	withTempHome(t)
+	runOK(t, "init")
+	db, _, err := openMigrated()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	insertSyntheticSearchArchive(t, db, 40)
+
+	reference := CodeReference{
+		Schema:        "brigade.code-reference.v1",
+		Repository:    "escoffier-labs/brigade",
+		Revision:      CodeRevision{Commit: strings.Repeat("a", 40)},
+		FilePath:      "src/brigade/receipts_cmd.py",
+		QualifiedName: "brigade.receipts_cmd._metadata_with_delta",
+		SymbolKind:    "function",
+		SourceSpan:    SourceSpan{StartLine: 787, LineCount: 3},
+		ChangeKind:    "changed",
+	}
+	metadata, err := json.Marshal(map[string]any{"code_references": []CodeReference{reference}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`update items set metadata_json = ? where id = 'item-001'`, string(metadata)); err != nil {
+		t.Fatal(err)
+	}
+	encoded, err := json.Marshal(reference)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	exactOnly := runJSON(t, "search", "--code-reference", string(encoded), "--json")
+	if results := exactOnly["results"].([]any); len(results) != 1 || results[0].(map[string]any)["id"] != "item-001" {
+		t.Fatalf("exact-only CLI search = %#v", exactOnly)
+	}
+
+	missing := reference
+	missing.ChangeKind = "removed"
+	missingEncoded, err := json.Marshal(missing)
+	if err != nil {
+		t.Fatal(err)
+	}
+	exactOnlyMiss := runJSON(t, "search", "--code-reference", string(missingEncoded), "--json")
+	if results := exactOnlyMiss["results"].([]any); len(results) != 0 {
+		t.Fatalf("exact-only nonmatch fell through to lexical search: %#v", exactOnlyMiss)
+	}
+
+	combinedFallback := runJSON(t, "search", "needle", "--code-reference", string(missingEncoded), "--limit", "5", "--json")
+	if results := combinedFallback["results"].([]any); len(results) != 5 || results[0].(map[string]any)["id"] != "item-030" {
+		t.Fatalf("combined CLI fallback = %#v", combinedFallback)
+	}
+
+	if code, _, stderr := run("search", "--code-reference", "{}", "--json"); code == 0 || !strings.Contains(stderr, "invalid code reference") {
+		t.Fatalf("malformed exact-only reference code=%d stderr=%q", code, stderr)
+	}
+	if code, _, stderr := run("search", "--json"); code == 0 || !strings.Contains(stderr, "usage: miseledger search <query>") {
+		t.Fatalf("missing query and reference code=%d stderr=%q", code, stderr)
+	}
+}
+
 func TestCodeReferenceIntegerVectorsAreAcceptedAndCanonicalized(t *testing.T) {
 	data, err := os.ReadFile(repoPath(t, "../../schemas/code-reference.v1.integer-vectors.json"))
 	if err != nil {

src/brigade/cli/__init__.py

@@ -34,6 +34,7 @@
     add as _add_group,
     setup as _setup_group,
     stations as _stations_group,
+    code as _code_group,
     pantry as _pantry_group,
     evidence as _evidence_group,
     search as _search_group,
@@ -105,6 +106,20 @@
 }
 
 
+_PASSTHROUGH_LEAVES = {
+    ("code", "sync"),
+    ("code", "context"),
+    ("code", "impact"),
+    ("evidence", "crawl"),
+    ("evidence", "search"),
+    ("search", "sync"),
+    ("search", "context"),
+    ("search", "impact"),
+}
+
+_PLAN_LEAVES = {("evidence", "crawl"), ("search", "sync")}
+
+
 def _register_extras(sub: argparse._SubParsersAction, name: str, extras_enabled: bool) -> None:
     if extras_enabled:
         _EXTRAS_MODULES[name].register(sub)
@@ -134,6 +149,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _add_group.register(sub)
     _setup_group.register(sub)
     _stations_group.register(sub)
+    _code_group.register(sub)
     _evidence_group.register(sub)
     _search_group.register(sub)
     _tokens_group.register(sub)
@@ -188,9 +204,24 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _peel_passthrough_engine_args(argv: list[str]) -> tuple[list[str], list[str] | None]:
+    """Keep opaque engine flags out of argparse for known passthrough leaves."""
+
+    leaf = tuple(argv[:2])
+    if leaf not in _PASSTHROUGH_LEAVES:
+        return argv, None
+    if leaf in _PLAN_LEAVES and len(argv) > 2 and argv[2] == "plan":
+        return argv, None
+    return argv[:2], argv[2:]
+
+
 def main(argv=None) -> int:
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    parse_argv, engine_args = _peel_passthrough_engine_args(raw_argv)
     parser = _build_parser()
-    args = parser.parse_args(argv)
+    args = parser.parse_args(parse_argv)
+    if engine_args is not None:
+        args.engine_args = engine_args
 
     # Command groups dispatch via set_defaults(func=...). The parser is attached
     # so dispatch functions can call parser.error for unreachable

src/brigade/cli/_common.py

@@ -42,6 +42,7 @@
             "tools",
             "mcp",
             "evidence",
+            "code",
             "search",
             "tokens",
             "pantry",

src/brigade/cli/code.py

@@ -0,0 +1,21 @@
+"""Executable GraphTrail facade commands."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("code", help="Run GraphTrail graph commands through Brigade.")
+    commands = parser.add_subparsers(dest="code_command", metavar="<code-command>")
+    commands.required = True
+    for verb in ("sync", "context", "impact"):
+        command = commands.add_parser(verb, help=f"Run `graphtrail {verb}`.")
+        command.add_argument("engine_args", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+    parser.set_defaults(func=dispatch)
+
+
+def dispatch(args) -> int:
+    from .. import code_cmd
+
+    return code_cmd.run(args.code_command, args.engine_args)