# Scanner registry

Use `brigadestack work scanners` to list your local scanners, plan run windows, and run them. `brigadestack work sweep` is the daily command that runs the configured scanners and writes one local report. Scanners run only from these commands, not from `brief` or `doctor`, and imports stay pending until you promote them.

The local config is gitignored:

```text
.brigade/scanners.toml
```

Create it with:

```bash
brigadestack work scanners init
```

## Commands

```bash
brigadestack work scanners list
brigadestack work scanners list --json
brigadestack work scanners show chat-memory-sweep
brigadestack work scanners plan
brigadestack work scanners plan --json
brigadestack work scanners doctor
brigadestack work scanners doctor --import-issues
brigadestack work scanners run chat-memory-sweep
brigadestack work scanners run chat-memory-sweep --ingest-output
brigadestack work scanners run --all
brigadestack work scanners run --due
brigadestack work scanners runs
brigadestack work scanners run-show <run-id>
brigadestack work sweep
brigadestack work sweep --all
brigadestack work sweep --scanner friction-scan
brigadestack work sweep --no-ingest
brigadestack work sweeps
brigadestack work sweep-show <sweep-id>
brigadestack work sweep-review latest
brigadestack work sweep-review <sweep-id>
```

`plan` calculates intended run windows from scanner cadence and timeout, detects overlapping or clustered scanner windows, and prints a suggested staggered schedule. `doctor` checks missing config, disabled required local producers, bad commands, missing or stale output paths, and schedule conflicts. With `--import-issues`, doctor writes scanner health warnings into the existing work import inbox as task imports.

`run` executes only configured scanner entries from `.brigade/scanners.toml`. It supports one scanner id, `--all`, or `--due`. Due runs compare each scanner cadence with the latest successful receipt. Disabled scanners are skipped unless `--include-disabled` is present. Existing running receipts block execution unless `--force` is present.

Execution is direct and foreground-only. BrigadeStack splits command strings into argv, rejects high-risk shell-like commands, refuses shell metacharacters, and calls the process without a shell. Scanner commands may write their own import records, and BrigadeStack stamps matching new imports with scanner run provenance when possible. It does not promote anything.

If a scanner declares `import_path` and `import_format = "jsonl"`, `brigadestack work scanners run ... --ingest-output` validates that JSONL output after a successful run and appends valid records to the work inbox with scanner provenance. Without `--ingest-output`, BrigadeStack records the run receipt and leaves output ingestion explicit. Malformed configured import output fails before BrigadeStack appends any records.

Scanner run receipts are gitignored under:

```text
.brigade/scanners/runs/
```

Each receipt includes the run id, scanner id, source, argv, cwd, started and completed timestamps, duration, exit code, timeout state, stdout/stderr summaries, full local log paths, and output path snapshots from before and after execution. Use `brigadestack work scanners runs` and `brigadestack work scanners run-show <run-id>` to review them. `doctor` also reports failed or timed-out runs, malformed receipts, missing logs, stale successful runs, and due scanners.

## Daily Scanner Runs

`brigadestack work sweep` runs due enabled scanners from `.brigade/scanners.toml` as one foreground command. It uses the same scanner execution path as `brigadestack work scanners run --due`, but defaults to ingesting each successful scanner's configured `import_path` when `import_format = "jsonl"`. Use `--no-ingest` to leave outputs untouched, `--all` to run every configured scanner, or `--scanner <id>` to run one scanner. Disabled scanners still require `--include-disabled`, and overlapping running receipts still require `--force`.

Sweep reports are gitignored under:

```text
.brigade/scanners/sweeps/
```

Each report includes the sweep id, started and completed timestamps, scanner run ids, scanner receipt paths, created import ids, skipped source fingerprints, dismissed source fingerprints, import counts, an inbox hygiene summary, and suggested next commands. Use `brigadestack work sweeps` and `brigadestack work sweep-show <sweep-id>` to inspect reports.

Use `brigadestack work sweep-review <sweep-id>` or `brigadestack work sweep-review latest` to triage what a sweep produced. Review output groups created imports by source, kind, priority, acceptance coverage, provenance completeness, and pending/promoted/dismissed state. Pending imports include exact next commands for `import plan`, `import promote`, `import dismiss`, `import promote --run`, `import plan-handoff`, and `import promote-handoff` as appropriate.

`brigadestack work brief` shows the latest sweep, suggests `brigadestack work sweep` when scanner runs are due, and surfaces the top pending import from the latest unreviewed sweep. `brigadestack work doctor` warns on missing, stale, failed, or unreviewed sweep reports, missing import references, lost provenance, and noisy no-op sweeps. `brigadestack work inbox doctor` also reports broken sweep import references.

A sweep ingests JSONL output into the work inbox as pending imports. It does not promote imports, edit memory, or change GitHub, and it runs in the foreground.

Inbox hygiene commands help keep reviewed scanner output from becoming queue clutter:

```bash
brigadestack work inbox doctor
brigadestack work inbox archive
```

`inbox doctor` reports pending scanner imports missing provenance, stale pending imports, promoted imports whose ledger task is missing, dismissed imports whose source fingerprint changed, noisy sources, and scanner runs that produced no imports despite a configured `import_path`. `inbox archive` moves old promoted, dismissed, and superseded imports to `.brigade/work/imports/archive.jsonl` while preserving pending imports.

## Config Shape

Each scanner is a TOML table:

```toml
[[scanner]]
id = "chat-memory-sweep"
source = "chat-memory-sweep"
command = "brigadestack work import chat-sweep --json"
cadence = "daily@02:15"
enabled = true
timeout = 300
output_path = ".brigade/chat-memory-sweeps/latest.json"
import_path = ".brigade/work/imports/chat-memory-sweep.jsonl"
import_format = "jsonl"
conflict_window = "02:00-02:30"
```

Fields:

- `id`: stable scanner id.
- `command`: command to run for this scanner.
- `source`: expected work import source.
- `cadence`: `daily@HH:MM`, `weekly@HH:MM` or `hourly@MM`.
- `enabled`: true or false.
- `timeout`: expected max runtime in seconds.
- `output_path`: local output or state file used for freshness checks.
- `import_path`: optional repo-relative JSONL import output for `--ingest-output`.
- `import_format`: optional import format. Only `jsonl` is supported.
- `conflict_window`: `HH:MM-HH:MM` window that should not overlap related jobs.
- `cwd` or `target`: optional repo-relative working directory for execution.

The default config ships nine producers. Four are enabled: `chat-memory-sweep` (chat sweep imports), `memory-refresh`, `handoff-ingest` (handoff ingest sync) and `friction-scan` (weekly, `weekly@05:00`). Five are disabled until you turn them on: `chat-surfaces`, `memory-care`, `backup-health`, `security-scan` and `tool-catalog`. Product-specific chat adapters and tool projection writers remain outside this registry phase.