tessary

An agent-reliability platform: ingest every trace, filter it with cheap classifiers, group the survivors into cases, and explain a case with an agentic root-cause run grounded in the customer's own repository. The .tessary/ pipeline bundle authored by the evals plugin (a Claude Code plugin in a separate repo) is an INPUT — it names call sites, failure modes and intent, and Layer-2 triage rules against it. Nothing in this tree synthesises, runs or scores a grader: this repo has no graders, datasets, experiments, review queues, or observer. Details: devdocs/reference/architecture.md.

The product thesis lives in Tessary's internal Agent Reliability document, not in this repo — see Strategic context at the bottom for the working summary. devdocs/reference/principles.md carries the standing engineering constraints, and devdocs/README.md maps the rest of the docs.

Architecture

                     ┌──────────────────────────────┐
                     │ Caddy (:8000) — reverse proxy │
                     └──────┬─────────────────┬─────┘
                  /api/*    │                 │   /
                            ▼                 ▼
              ┌──────────────────┐   ┌──────────────────┐
              │ Spring Boot      │   │ Vite dev (:5173) │
              │ backend (:8080)  │   │ or static build  │
              │ — JVM + Loom     │   │ React + TS       │
              └────┬─────────────┘   └──────────────────┘
                   │ reads / writes            + groundedness model (serve.py on
                   ▼                             your own GPU, outside Docker)
                Postgres (pgvector; per-project pipeline, substrate, findings, cases)

Repo map

Before editing under backend/ or frontend/, read that directory's AGENTS.md. Running the stack locally: devdocs/guides/local-dev.md. Tessary's own hosted deployment is documented privately and is not part of the public export. Cross-stack recipes (schema change, new classifier): devdocs/guides/common-tasks.md. Config keys: devdocs/reference/config-keys.md.

Universal rules

• No comments in code changes unless they explain a non-obvious invariant, a workaround for a specific bug, or behavior that would surprise a reader. Well-named identifiers are the documentation.
• NEVER keep old implementation as fallback. Delete dead code.
• No example files or demo code unless explicitly requested.
• User-visible copy follows handbook/voice-and-tone.md. Plain words, active voice, no em-dashes, no hedging. Applies to UI strings, errors, Slack, CLI output and docs prose; not to code comments.
• The schema is the source of truth. The evals plugin owns the bundle schema; absorb changes in order: contract/ → backend records → frontend types → views. The plugin still emits grader and quality-dimension shards this tree has nothing to run; BundleAssembler routes them to Shard.IGNORE rather than rejecting the bundle, and that is deliberate.
• Python uses uv, never pip or poetry. classifiers/ owns a pyproject.toml + uv.lock; run uv lock after any dependency change and commit both.
• Node packages use pnpm, never npm. Each has its own pnpm-lock.yaml; they are deliberately NOT a workspace, so every Dockerfile can build from its own directory. Two consequences worth knowing before you touch one: pnpm 11 keeps settings in pnpm-workspace.yaml rather than the pnpm field in package.json (which it ignores silently), and dependency build scripts are blocked unless allowlisted there under allowBuilds. The single exception is the in-sandbox npm install in sandbox-runner/agent-sandbox/template.ts, which is intentional.

Tests

• Expected values come from the requirement, never from running the code. Derive them from the issue, spec, or a hand calculation before implementing.
• Test first, watch it fail. Run the test red for the right reason, then implement. A bug fix's test goes red again when the fix is reverted; a test on a helper the fix didn't touch doesn't count.
• Every test names the bug it catches. If you can't name one, don't write it. Don't add tests to code you didn't change unless asked.
• Never weaken a test to get green: no skipping, loosening, or re-baselining. If a test looks wrong, or breaks on a pure refactor, stop and ask.
• Delete a test only when it is proven redundant. For unit-testable code, PIT's full mutation matrix shows kept tests kill every mutant it kills, and it is not the only test pinning what PIT can't mutate (literals, tables, tuning constants); for an integration test PIT can't run, per-test coverage shows no branch lost and a read confirms a kept test asserts the same behaviour.
• Report each new test in your summary: the bug it catches and its red output.
• How to write them: backend/AGENTS.md, frontend/AGENTS.md.

Working loop

• Batch independent tool calls; don't batch dependent find→read chains.
• Prefer Read/Grep over dumping files through the shell; edit only after reading constraints in this file + the scoped AGENTS.md.
• Iterate on task check -- <slices>; gate on bare task check.

Validation

Run the slices your change touches (task check -- rca,metering or task check -- frontend), and the bare task check before merging. CI runs the same gate on every pull request that touches code — .github/workflows/check.yml calls scripts/check.sh, the same manifest task check runs, so local green means CI green by construction. A prose-only diff is filtered out by that file's paths-ignore (prose is Mintlify's check to run, not this pipeline's), and a draft PR is skipped until it is marked ready. secret-scan.yml also runs on every pull request. Two workflows run on a cron: price-book-refresh.yml daily and codeql.yml weekly (Mondays 04:00 UTC). Everything else is workflow_dispatch: only. Nothing is merge-blocking (branch protection is plan-gated on this tier), so a red check still has to be respected by a human. Docker is required for any backend slice. Full cost model and recount commands: devdocs/reference/test-suite.md.

Documentation policy

Where a new piece of documentation goes, by kind:

1. Imperative rule an agent must follow while editing code under a directory → that directory's AGENTS.md (backend/, frontend/); this root file only for rules that apply repo-wide.
2. Lookup / reference material (tables, inventories, schemas, topology) → devdocs/reference/.
3. Step-by-step runbook or cross-stack recipe → devdocs/guides/.
4. Why-explanations of a subsystem → devdocs/concepts/.
5. Durable engineering constraint → devdocs/reference/principles.md. Product thesis, positioning, and market framing do NOT live in this repo — they live in Notion, and a PR that adds a strategy doc here is adding a second source of truth that will go stale.
6. Deferred or planned work → the roadmap, which is maintained privately and is not part of the public export.

Rules that keep this working:

• One home per fact. Never duplicate a rule across files — restate at most one line and link to the owning doc.
• Same-PR co-update. A code change that invalidates any of these docs updates the doc in the same PR (schema changes update devdocs/reference/data-model.md; package-set changes update the architecture inventory; controller/DTO changes regenerate the OpenAPI spec). The classifier-quality reference page is devdocs/reference/classifier-quality.md; its gate scripts/check-classifier-quality-doc.sh pins the page's model revision and threshold to classifiers/groundedness/serve.py and the catalog.
• Size budgets. This file stays ≤ ~150 lines; a scoped AGENTS.md ≤ ~250. When a budget is blown, extract reference material to devdocs/reference/ instead of growing the guide.
• New top-level code directory → gets a README.md; add an AGENTS.md only once it accrues agent-imperative conventions (the frontend/ precedent).
• After moving or renaming a doc, grep -rn for the old path and retarget every link in the same PR.

Strategic context

Enough to make a design call without leaving the repo; the full thesis is Tessary's internal Agent Reliability document, which is authoritative and the only place it is maintained.

We watch every production trace — not a sample, because once an agent is mature every failure is a low-percentage failure and sampling structurally cannot find them. A cascade of cheap classifiers filters the potentially-bad ones, which are grouped into failure modes and root-caused against the customer's repo. We sell the cause, not the chart.

The moat is that cheap filter, which yields two rules for code in this repo:

• Anything that scales per-event LLM cost with ingest volume attacks the product directly. LLM work is the escalation, applied to what a cheap filter already flagged — never the default detection path. (There are two recorded exceptions, frustration and an extension classifier's per-match call; their conditions are in devdocs/reference/principles.md.)
• An unmeasured detector is a liability, not a feature. A filter's false-positive rate at a stated alert budget is the asset.

If a choice in the codebase doesn't fit that framing, surface it before implementing.

devdocs/reference/principles.md § Product & positioning now carries only the engineering constraints that fall out of this framing; the framing itself is maintained in Notion and summarised above.