lev-os/agents/ubs

UBS

Use ubs as a scoped gate. Keep the scope tight unless the user explicitly wants a full baseline scan.

Prerequisites

command -v ubs

If missing, stop and tell the user:

brew install dicklesworthstone/tap/ubs

Golden Rules

1. Prefer --staged, --diff, or explicit files over ubs ..
2. Use --format=json when you need machine-readable output.
3. Re-run after fixes to confirm the exit code is clean.
4. Treat UBS as a tool boundary; do not import its repo-level hooks as implicit Lev policy.

Fast Path

ubs --staged --format=json --ci

If you only changed a few files:

ubs path/to/file.ts path/to/other.py --format=json --ci

Core Commands

Narrow scans

ubs --staged --format=json --ci
ubs --diff --format=json --ci
ubs src/file.ts src/other.py --format=json --ci

Full or filtered scans

ubs . --format=json --ci
ubs --only=js,python . --format=json --ci
ubs --category=resource-lifecycle . --format=json --ci

Diagnostics

ubs doctor
ubs doctor --fix

Recommended Workflow

Before commit

ubs --staged --fail-on-warning --format=json --ci

During review

1. Scan only the touched files.
2. Inspect critical findings first.
3. Fix root causes, not symptoms.
4. Re-run the same narrow scan.

Output Handling

Focus on:

• summary
• findings[].file
• findings[].line
• findings[].severity
• findings[].category
• findings[].message

If the user wants GitHub or CI artifacts:

ubs . --format=sarif --ci
ubs . --report-json .ubs/latest.json --html-report .ubs/latest.html --ci

When Not To Use UBS

Do not default to UBS when:

• the user wants architectural review rather than static findings
• there are no changed files and no request for a baseline scan
• another domain-specific checker is clearly more appropriate

Anti-Patterns

• Running ubs . on every small edit
• Ignoring critical findings without checking the code
• Treating UBS findings as proof without context
• Installing repo hooks or settings from the upstream repo without explicit user approval

Minimal Report Pattern

## UBS Findings
-Scope scanned:
-Critical:
-Warnings:
-Follow-up fixes:

Keep the summary in the active Lev artifact or review comment, not in detached scratch notes.