mailroom-reloaded

Imported from Exios66/mailroom-reloaded (AGENTS.md). Install upstream with npx skills add Exios66/mailroom-reloaded. Copyright stays with the author.

AGENTS.md — operating contract for mailroom-reloaded

This is the governance and operating contract for any AI agent (OpenCode, Cursor, Claude Code, Codex) working in this repository. Read it first, every session. It is the truth for how to work here; docs/ is the truth for behavior, and docs/superpowers/archive/DISCUSSION_BOARD.md (history only) is the work log.

• Canonical checkout: a clone of Exios66/mailroom-reloaded. Work happens on a feature branch cut from main (see §8.1); main is the only long-lived branch.
• Plan: docs/superpowers/plans/v1.md (one page). New work must trace to an eval finding or an issue listed there. Do not add workstreams to the plan; open an issue instead. Older plans are history under docs/superpowers/archive/.
• If a statement here conflicts with README.md, docs/ARCHITECTURE.md, the design spec (docs/superpowers/specs/2026-10-07-mailroom-reloaded-design.md) or the plan (docs/superpowers/plans/v1.md), the more specific document wins, and this file must be corrected in the same change that reveals the conflict.

1. What this repo is

mailroom-reloaded is the compressed, deployment-ready Digital Mailroom: a CrewAI-Flows pipeline that ingests documents, classifies and extracts them, and archives them with a verifiable audit chain, plus an evaluation harness that scores runs against Lucius-Morningstar/mailroom-dataset.

• Dev source of truth. This checkout is where all code, docs, schemas and contracts are authored and reviewed. Do not treat a deployed image or a data/ tree as authoritative.
• Package/release law (DMR-074). Where an external package repo mirrors a subtree, the monorepo is the dev source of truth and propagation is via the packaging/sync tooling — never by hand-editing a mirror or pushing a standalone repo directly. A deliverable that must reach an external repo is a sync unit on the card: plan it, execute it, and cite the sync evidence.

2. Startup ritual (every session)

1. State your harness and canonical checkout. Name the tool you are running under (OpenCode / Cursor / Claude Code / Codex) and the absolute path of the checkout you consider canonical. Do not silently operate in a mirror.
2. Read the governing documents for the mission scope, in order: AGENTS.md (this file) → docs/superpowers/archive/DISCUSSION_BOARD.md (work log, history only) → the relevant docs/*.md → the plan/spec under docs/superpowers/. For a package task, also read that package's own AGENTS.md/README if one exists.
3. Prefer read-only inspection and cheap mocks before live spend or deploy. The default provider is mock. Do not reach for a live provider, a GPU, Modal, or a network pull until a cheaper path has been ruled out and the task actually needs it.
4. Claim before you edit. For board-tracked work, claim the card (lane + Owner) before touching code; label before code; close with proof.
5. Do not run git write commands (add/commit/checkout/push/tag) unless the task explicitly asks for them. Reading git (status, log, diff, show) is always allowed.
6. Leave the tree consistent: a behavior change carries its doc/changelog update and its test in the same change. Docs-only changes say so.

3. Architecture & routing

3.1 Pipeline

The canonical stage order is NODE_ORDER in src/mailroom_reloaded/pipeline/state.py:

ingest ─▶ bert_primary ─▶ sort ─▶ gate_classify ─┬─▶ extract ─▶ gate_extract ─┬─▶ report ─▶ catalog ─▶ archive ─▶ [grade]
 (det.)      (local)      (LLM 1)                │   (LLM 2)                 ├─▶ retry_extract (≤ retry_max)
                                                 ├─▶ re_sort (FULL, once)    ├─▶ verify: judge ─▶ arbiter
                                                 └─▶ human_review (park)     ├─▶ boss (escalation)
                                                                             └─▶ human_review (park)

• Two-LLM-call fast path: a clean text-layer document costs exactly two LLM calls (sort + extract); routing is a deterministic gate, not a reviewer LLM (pipeline/flow.py). ingest and bert_primary are local.
• Owner of control flow: MailroomFlow._drive_nodes (a deterministic driver), not CrewAI's event engine. The @start/@listen/@router methods exist so the class is routable/plottable.
• Gate: src/mailroom_reloaded/agents/gate.py — BandGate by default, LearnedGate when models/route_gate.json exists, JevGate when the opt-in MAILROOM_JEV_PROVIDER is set and a calibration exists. Jev overrides only the medium band, never a hard rule (docs/JEV.md).
• Durability: filesystem bins + JSON manifests + a SQLite hash-chained audit log (storage/bins.py, storage/audit_log.py); a crash resumes from the manifest's last completed node (watcher.py).
• Archive ledger: a second, global hash chain over every run (storage/ledger.py), with optional off-host anchoring (storage/anchor.py, mailroom audit ...).

3.2 Agent roster (src/mailroom_reloaded/agents/)

3.4 How a task routes to a surface

4. Directory map

5. Scripts & commands

5.1 Makefile targets (verbatim)

5.2 mailroom CLI groups (defined in src/mailroom_reloaded/cli.py)

Console script mailroom = mailroom_reloaded.cli:main (pyproject.toml). There is no mailroom tui subcommand — /tui is a browser route served by the API (see §7.5).

5.3 scripts/

6. Test tiers

pytest (auto async mode) + ruff. Config lives in pyproject.toml: testpaths = ["tests"], asyncio_mode = "auto", addopts = "--strict-markers -m 'not live and not docker'", and two registered markers, live and docker.

Run:

uv sync --extra dev                       # core + pytest/ruff
uv run pytest -q                          # live deselected by addopts
uv run pytest tests/pipeline -v           # one tier
MAILROOM_LIVE=1 uv run pytest -m live -v  # live tests (needs a configured provider)
uv run ruff check .                       # lint (vendored scoring excluded)
node --test tests/tui/js/*.test.mjs       # TUI JS unit tests
node --test tests/ui/js/*.test.mjs        # /ui JS module unit tests
uv run pytest tests/test_dependency_fence.py -q

• live marker. Tests that hit a real provider are @pytest.mark.live and are deselected by default; -m live (with MAILROOM_LIVE=1) selects them.
• docker marker. tests/deploy/test_docker_smoke.py::test_docker_smoke_script runs scripts/docker_smoke.sh (builds images); deselected by default, -m docker selects it and it skips when the daemon or registry is unavailable.
• parity extra. The scoring-parity test skips unless llm-dojo-scoring v0.21.0 is installed (uv sync --extra parity).
• Dependency fence. No langgraph, langchain*, langfuse, braintrust or litellm under src/ or in any dependency.
• Prompt lock. tests/test_prompts.py verifies every vendored prompt's sha256 against lineage.json.
• Extras: bert, eval, gmail, embeddings, deploy, anchor, dev, parity (pyproject.toml). Never uv sync --all-extras (torch).

7. Workflows

7.1 Dev server stack (Docker)

scripts/dev.sh up        # or: make dev   — mock provider, no GPU
scripts/dev.sh status
scripts/dev.sh logs
scripts/dev.sh smoke     # upload a fixture, wait for "archived"
scripts/dev.sh down      # or: make dev-down

Brings up app (--reload), a separate watcher, the mock provider, otel-collector, phoenix, prometheus, grafana. All ports loopback. Never run the embedded watcher and the standalone watcher against the same data dir (the watcher.lock flock admits one draining process).

7.3 Evaluation posture

uv run mailroom eval --classes contract,merger_agreement --per-class 10
uv run mailroom eval --mode specialist_cell --gpus 2 --concurrency 32 --prompt-set sand37
uv run mailroom train-gate --rows rows.jsonl --out models/route_gate.json

Fit the gate/calibration on split=train only; report KPIs on test (docs/EVALUATION.md). Write cards with mailroom card; serve them from <base_dir>/runs/<run_id>/cards/.

7.4 Gmail intake

uv run mailroom gmail auth
uv run mailroom gmail poll --limit 25 --process
uv run mailroom gmail watch --interval 30 --process

Needs the gmail extra; OAuth token/state live under the base dir (docs/gmail-intake.md). The Pub/Sub push route is POST /v1/intake/gmail.

7.5 TUI (/tui) and web UI (/ui)

• /tui is a browser terminal served by the API (src/mailroom_reloaded/api/tui/), static ES modules, no build step. Commands include ls, inspect, audit, jev, review, resolve, runs, ledger, replay, cards, auth (docs/TUI.md).
• /ui is the vanilla-JS runs/documents page (api/ui/index.html).
• Host harness: scripts/tui_dev.sh up|down|status (mock LLM + API + embedded watcher; state under data/tui-dev/). JEV=1 also starts/calibrates the mock Jev.

8. Conventions

• Python. requires-python = ">=3.11,<3.13". Keep ruff check . clean. The vendored src/mailroom_reloaded/scoring/ files are excluded from lint and must keep upstream bytes (see scoring/PARITY.md).
• Tests. pytest-asyncio in auto mode (no @pytest.mark.asyncio needed). Use the registered markers only (--strict-markers); mark live tests live. tests/conftest.py clears the settings/taxonomy lru_cache around every test, so do not cache config across tests.
• Commit messages (observed, not enforced). The repo mixes Conventional Commits scopes with plain imperative subjects:
  • feat(<scope>): …, fix(<scope>): …, test(<scope>): …, docs: …, docs(<scope>): … — scopes seen: tui, replay, obs, jev, anchor, metrics, ledger, deploy, board, plans, review, llm.
  • Plain subjects like Add /ui replay links and #replay= deep link in /tui, Replay viewer: …, Generate docstrings for PR #28.
  • Merge commits: Merge pull request #N from Exios66/<branch>.
  • There is no commitlint/CI gate observed. Follow the dominant pattern: a scoped prefix for typed changes, a plain imperative subject otherwise; a body explaining the "why"; Co-Authored-By: / Claude-Session: trailers where the harness adds them.
• Changelog. CHANGELOG.md follows Keep a Changelog; behavior-changing work adds its [Unreleased] entry in the same change, naming files and the numbers that motivated it. Docs-only changes declare themselves as such.
• Targeted staging. Stage only the files in the card's scope; never reformat or reflow unrelated files.
• No GitHub Actions assumptions. Do not assume a CI runner exists for your change; run the tiers locally (scripts/dev_test.sh, or uv run pytest + uv run ruff check .) and cite the output.
• Timestamps. UTC ISO-8601 (%Y-%m-%dT%H:%M:%SZ) in evidence and Owner cells; bare dates are UTC by convention.
• Derived artifacts. Never hand-edit generated/derived files — regenerate them.

8.1 Git, branches, PRs and review

• Branches. main only long-lived. Feature branches are feat/<topic>, fix/<topic> or docs/<topic>; agent sessions use the claude/<topic> branch the harness names. Never push to a branch you were not assigned; never force-push or rewrite another session's branch (merge main in instead).
• Stacked PRs. Base a PR on its parent's branch and say so in the PR template (stack_parent). After the parent merges, retarget the child to main, merge main into it, and re-run the gates before merging it.
• Commits. Scoped prefix per §8, body explaining why. Agent commits end with the trailers the harness supplies (Co-Authored-By:, Claude-Session:). Never put a model identifier in a commit, PR, code comment or changelog.
• Merging. Merge commits (no squash, no rebase) via the GitHub API with the full 40-character expectedHeadSha. A PR is mergeable only when its gates pass locally, the [Unreleased] entry exists, and every CodeRabbit finding is either applied or answered (below).
• Merge state. Verify per branch, never from a summary: after git fetch --all --prune, run git merge-base --is-ancestor origin/<branch> origin/main (exit 0 = merged) or git branch -r --merged origin/main. A note, plan or PR list is not evidence.
• CodeRabbit. Do not wait for it to finish when it is overloaded. Apply each finding unless it is flawed; verify against current code first (trace a real caller to the failure). Reply on a thread only to explain why a finding is not applied. Nits and optional findings ride along with the next real push. Salvage stranded tests from coderabbit/* branches into a normal PR; never merge those branches directly.
• Comments on GitHub are rare and end with the footer --- then _Generated by [Claude Code](https://claude.ai/code)_. PR descriptions end with the harness attribution lines.
• Branch pruning. Delete a remote branch only after verifying it is merged into origin/main (or that its useful content is salvaged and cited). Never delete the branch of an open PR.
• Workers. An orchestrating agent may run workers in parallel (medium-effort Sonnet or high-effort Haiku, effort set explicitly). Workers edit and test but never touch git; one adversarial reviewer vets the diff before the orchestrator commits.

8.2 Issue forms and the PR template (machine-readable)

Forms live in .github/ISSUE_TEMPLATE/*.yml; blank issues are disabled. GitHub renders each field as a ### <Label> heading in the issue body, so agents can parse an issue by heading. Field ids are stable; do not rename them.

• Working an agent-task card: touch only scope_paths, never out_of_scope; do not exceed autonomy_level (read-only analysis < edit locally, no git < branch + commit < branch + commit + open PR); run the listed gates; finish with the definition_of_done report.
• Deferred review findings become follow_up issues (or entries in the master plan's follow-up list), not silent TODOs.
• PR template. .github/pull_request_template.md ends with a fenced agent-report YAML block (schema: 1) with change_type, scopes, linked_issues, plan_items, stack_parent, gates (ruff, pytest, node_test, browser_check: each pass|fail|skipped), coderabbit, not_verified, follow_ups. Keep the exact shape, fill every key (null or [] when empty), and never mark a gate pass you did not run.
• Gates for this repo: ruff check src tests; PYTHONPATH=src pytest -p no:cacheprovider tests -q; node --test tests/tui/js/*.test.mjs; node --test tests/ui/js/*.test.mjs; scripts/tui_replay_check.mjs for TUI changes; scripts/docker_smoke.sh (optional, only when deploy/** or a Dockerfile input changes; prune the build cache afterwards on a small disk). There are no GitHub Actions workflows (the owner's account cannot run them; docker-smoke.yml was removed 2026-10-10), so there is no hosted CI: paste the result lines into the PR.

9. Evidence contract

Every deliverable carries evidence that a reviewer can re-run.

• Cite exact paths, commands and test names. No "should work" without a run. State the command and the result line.
• Classify every finding as one of: harness (agent tooling/config) | vendored upstream (pinned third-party bytes/code) | operator/env (missing key, no Docker, no provider) | model (LLM behaviour).
• Docs changes: show the drift sites before/after and the gate command that proves the docs now match reality (reference audit, a --check/validate run, a content validate).
• Board work: show the card's lane/Owner/Evidence before/after, the board check result, and (for synced cards) the issue link.
• Test claims: name the tier and the command, not just a count; a green number without the command is not evidence.
• Ledger/audit claims: mailroom audit verify (and --external when the anchor is in scope); report exit codes.
• If you cannot run commands, list the exact commands and what a passing run looks like — never imply you ran them.

10. Subagent delegation roster

One specialist per concern. The caller owns and ships the work; the specialist produces a bounded deliverable with its own evidence. Brief like a card (scope, files, definition of done, evidence). Chain specialists, never impersonate one; verify upstream docs before writing config.

No in-repo subagent registry exists yet; the names below are the canonical roster established by this file. When a harness owns its own roster ids, map them here rather than forking new names.

Dispatch laws:

1. One specialist per concern. Do not ask one specialist to do another's job; chain them.
2. Brief like a card. Give scope, files, definition of done, evidence.
3. The caller owns and ships the work. A specialist's output is an input to your deliverable, not a substitute for it.
4. Verify upstream docs before writing config. Do not guess an API shape.
5. Chain, never impersonate. Attribute a specialist's contribution; do not restate it as your own finding.

11. Do / Don't

Do

• Read AGENTS.md + the relevant docs/ before editing.
• Prefer the mock/offline/mock-LLM path before live spend or deploy.
• Add the [Unreleased] changelog entry and the test with the behavior change.
• Keep docs, AGENTS.md and the board reconciled in the same change.
• Propagate package work via the sync tooling.
• Run the touched tier(s) and cite the command + result.

Don't

• Never commit secrets (keys, tokens, .env values) or print them; use env vars and redaction.
• Don't fork long-lived copies of agent configs or mirrors without syncing them back to their home.
• Don't weaken the token gate, the off-loopback bind refusal, the network guard, or trace masking to make a test pass.
• Don't run git write commands unless the task asks; never force-push, skip hooks, or create empty commits.
• Don't edit vendored scoring/ bytes or files lint-excluded on purpose.
• Don't report a green suite without the command that produced it.

12. Pointers

• README.md — overview, install, CLI/API tables, quickstart.
• docs/ARCHITECTURE.md — pipeline, durability, audit, module map.
• docs/CONFIGURATION.md — every env var and taxonomy.yaml block.
• docs/DEV_SERVER.md — local dev-server workflow.
• docs/EVALUATION.md — dataset, train/test discipline, cards.
• docs/JEV.md — the opt-in Jev decision model.
• docs/OPERATIONS.md — watcher, review, audit/ledger, observability, failure modes.
• docs/RUNBOOK.md — clone-to-demo paths A/B/C.
• docs/TESTING.md — tiers, live marker, dependency fence, parity.
• docs/superpowers/plans/v1.md — the one-page plan.
• docs/TUI.md — /tui commands, replay viewer, themes, auth.
• docs/gmail-intake.md — Gmail intake setup and limits.
• deploy/README.md — Modal vLLM deployment and teardown.
• docs/superpowers/archive/DISCUSSION_BOARD.md — agent work log (history).
• CHANGELOG.md — Keep a Changelog.
• docs/superpowers/specs/2026-10-07-mailroom-reloaded-design.md and docs/superpowers/plans/ — design and plans.