Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

Docs / Reference

Scanner registry

Configure local scanners, read their run receipts, and run them together once a day.

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:

.brigade/scanners.toml

Create it with:

brigadestack work scanners init

Commands

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:

.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:

.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:

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:

[[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.