Architecture Review

`saedra review`

Validate the current diff against all violation rules and active architectural decisions. Loads changed files via git diff HEAD, fetches rules and decisions from the project, sends everything to the configured AI, and reports per-file results.

Each file is classified as violation (clear rule breach), warning (potential issue without direct evidence), or ok (compliant). Output is grouped by severity: violations first, then warnings, then ok files.

Requires AI to be configured first via saedra ai setup.

$ saedra review

  Architectural Review

  ──────────────────────────────────────────────────

  ⚠  VIOLATION  packages/cli/src/commands/projects.ts
     Controller importing db-connector bypasses the query abstraction layer.
     Violates: RULE-2026-03-23-controllers-cannot-impor — Controllers cannot import db-connector directly
     Detail:   Import of @repo/db-connector found on line 3
     Decision: DEC-2026-03-04-use-document-type-fie

  ⚡  WARNING  apps/api/src/routes/teams.ts
     Import pattern is unusual but no direct rule applies.
     Relates to: RULE-2026-03-23-controllers-cannot-impor — Controllers cannot import db-connector directly
     Detail:     Indirect dependency on db-connector via a shared utility — worth reviewing

  ✓  OK  packages/db-queries/src/teams.ts
     New module follows the existing db-queries pattern.

  ✓  OK  packages/project-service/src/index.ts
     No architectural concerns.

  ──────────────────────────────────────────────────

  Result: 1 violation, 1 warning, 2 ok — review before opening PR

Reviews are capped at 20 files per run. If the diff exceeds that, only the first 20 files are analyzed and the output notes how many were skipped. Individual file diffs are also truncated if they exceed 3000 characters — the output warns when this happens and results for that file may be incomplete.

After each review, results are saved to the project on the server (branch, file list, violation count). This happens silently and is skipped when using --offline.

`saedra review --staged`

Analyze only files in the staging area (git diff --staged) instead of all changes since HEAD.

$ saedra review --staged

`saedra review --json`

Output results as JSON. Exits with code 1 if any violations are found — intended for CI pipelines.

$ saedra review --json
{
  "project": "my-infra",
  "total_violations": 1,
  "summary": { "violations": 1, "warnings": 0, "ok": 1 },
  "files": [
    {
      "file": "packages/cli/src/commands/projects.ts",
      "status": "violation",
      "violations": [
        {
          "rule_id": "RULE-2026-03-23-controllers-cannot-impor",
          "detail": "Import of @repo/db-connector found on line 3"
        }
      ],
      "note": "Controller importing db-connector bypasses the query abstraction layer."
    },
    {
      "file": "packages/db-queries/src/teams.ts",
      "status": "ok",
      "violations": [],
      "note": "New module follows the existing db-queries pattern."
    }
  ]
}

Use in GitHub Actions:

- name: Saedra Architecture Review
  run: saedra review --json
  env:
    SAEDRA_API_URL: ${{ secrets.SAEDRA_API_URL }}

`saedra review --base <ref>`

Compare files changed between a git ref and HEAD instead of using the working tree. Useful in CI to review only the commits in a PR branch.

$ saedra review --base origin/main

`saedra review --offline`

Skip the server entirely and use the local .saedra-context.json snapshot. Exits with an error if no snapshot is found.

$ saedra review --offline

If the server is unreachable but a snapshot exists, saedra review falls back to the snapshot automatically and prints a warning to stderr. --offline forces this path without attempting the server at all.

CI workflow (offline)

The recommended pattern for CI environments without persistent server access:

- name: Snapshot architecture context
  run: saedra memory compress
  env:
    SAEDRA_API_URL: ${{ secrets.SAEDRA_API_URL }}

- name: Architectural review (offline)
  run: saedra review --base origin/main --offline --json

saedra memory compress runs once (e.g. on a schedule or before the pipeline) and writes .saedra-context.json to the workspace. The review step then uses the snapshot without requiring server access during the review itself.

Architecture Review

saedra review

saedra review --staged

saedra review --json

saedra review --base <ref>