Skip to main content
Optimizations turn audit recommendations into a hosted backlog. Policies (Alpha) turn selected recommendations into hosted guardrail drafts that can be reviewed before activation.
Optimizations and policies are hosted workspace features. Run local audits for free, then push the audits you want to track in the hosted dashboard. Optimizations work on any workspace; Policies (Alpha) require Team, Growth, Scale, or Enterprise.

​
Optimizations backlog

The backlog is built from the latest active pushed audits. It combines:
  • modeled items from v2 recommendations
  • provisional opportunities when an older audit has findings but no modeled recommendation object
  • recurrence signals when similar opportunities appear again
Use filters for status, source, severity, category, implementation surface, recurrence state, and time range. When the backlog is empty, the dashboard explains why instead of showing one generic message:
  • filtered results offer to clear the filters
  • no active audits link to audit setup and history
  • incomplete active-audit coverage links to the affected audits and sources without claiming there are no opportunities
  • a no-opportunity conclusion states how many fully assessed active audits support it and separately discloses any incomplete audits excluded from that conclusion
The list API exposes the same additive result as meta.emptyState, including the reason and fully assessed/incomplete active-audit counts.

​
Lifecycle board

The prioritized list remains the default. Select Board or open ?view=board to see Open, Implemented, and Validated as three lifecycle columns. The board returns at most 25 cards per column in one bounded request, while each column keeps its full count and provides View all when more items exist. The list includes snoozed items by default. The board excludes them by default so deferred work does not crowd the active workflow; use the snooze filter to include snoozed items or show only snoozed items. View and filter choices remain in the URL. Workspace admins can move modeled items only through supported transitions:
  • Open to Implemented
  • Implemented to Open or Validated
  • Validated to Open
Moving an Implemented item to Validated opens its Optimization detail first and requires a compare audit. Provisional items stay visible but cannot be dragged because they do not have the modeled validation workflow. Archive and restore remain explicit menu actions, and Compare’s evidence-recurrence columns remain derived evidence rather than a mutable board. Lifecycle controls require both the current Clerk organization role and Xerg’s stored workspace role to identify the user as an admin. If those signals disagree, the board is read-only and the API still rejects unauthorized mutations.

​
Lifecycle statuses

Optimization items move through:
  • Open: the opportunity still needs work
  • Implemented: a change was shipped or the operational fix was made
  • Validated: a compare audit was selected to prove the result
  • Archived: the item is no longer relevant
Modeled items can store a validation link to a pushed compare audit. Use the same effective source and a compatible audit window so the before/after comparison is meaningful.

​
Fix with Xerg

Open an Optimization and use Fix with Xerg to copy an agent-ready Markdown task. It extends the existing detail drawer: the same evidence, where-to-change guidance, actions, checklist, policy suggestion, read-only Cedar note, and compare workflow remain in place. Every optimization user can copy the bounded task. Paid hosted-MCP users also see the exact xerg_get_optimization retrieval instruction so a coding agent can fetch the current handoff by optimization_id before editing. The handoff contains safe evidence summaries, source and measurement references, implementation steps, lifecycle timestamps, links, policy eligibility, and the latest immutable validation summary. It never contains Cedar policy text, prompts, responses, tool arguments or results, and it never changes code automatically. GET /v1/optimizations/:id resolves the same workspace-owned detail outside the active list filters or page. It enforces the workspace history entitlement before returning the Optimization and OptimizationHandoffV1. Validation display distinguishes three states:
  • Qualified savings: $X for a qualified immutable fact
  • Validation recorded plus the evidence reason for an unqualified fact
  • Validation details unavailable when no fact is stored
A missing legacy fact is never presented as pair_cap_exhausted.

​
Create a Linear issue

Team, Growth, Scale, and Enterprise workspace admins can connect Linear under Settings → Integrations, choose one accessible Linear team, and create an issue from an Optimization. Xerg creates at most one issue per Optimization; subsequent requests return the stored issue link. The issue uses the same bounded Fix with Xerg handoff. It contains the evidence summary, where-to-change guidance, actions, checklist, estimate qualification, validation instructions, and Xerg link. It does not send prompts, responses, tool arguments or results, system instructions, headers, arbitrary attributes, or Cedar policy text. This is a one-way handoff. Xerg does not create issues automatically, receive Linear webhooks, copy comments, synchronize statuses, or change an Optimization lifecycle status when the Linear issue changes. Disconnecting Linear revokes the integration credentials but preserves already-created issue links.

​
Recommendation fields

The current v2 recommendation contract includes:
  • priority bucket: fix_now, test_next, or watch
  • implementation surface, such as retry_policy, loop_guard, model_routing, scheduler, prompt_builder, or user_behavior
  • category, severity, confidence, effort, and estimated savings
  • scope label, where-to-change guidance, validation plan, and action steps
These fields are generated by the CLI and preserved in the push payload, dashboard, hosted MCP, and @xerg/schemas.

​
Policies (Alpha)

Policies are hosted rules associated with the workspace. A policy has a status, scope, action, threshold metric, threshold value, source, and optional recommendation reference. Current policy status values are:
  • draft
  • active
  • paused
Current scopes are:
  • workspace
  • source
  • workflow
Signed-in workspace admins can create, update, and delete policies. Workspace API keys can create idempotent recommendation-backed draft policies through the recommendation flow, but they cannot make arbitrary manual policy changes.

​
Cedar previews

When policy generation is enabled, Xerg stores Cedar policy text and version metadata with the policy. Policy creation and updates return validation errors if Cedar generation, parsing, or validation fails. Use draft status while evaluating a rule. Promote to active only after the team agrees on the threshold and scope.

​
Hosted MCP write safety

Hosted MCP exposes both read tools and guarded write tools. Write tools use preview and commit semantics so clients can inspect the planned change before committing it. Relevant tools include:
  • xerg_get_optimization
  • xerg_recommendations
  • xerg_list_policies
  • xerg_upsert_policy
  • xerg_delete_policy
  • xerg_create_policy_from_recommendation
Use hosted MCP for client configuration and the full tool list.