Project Monitoring

Overview

Guardian's Project Monitoring feature is the intake surface for AI-generated code before release. It continuously analyzes risky change patterns, applies policy checks, and feeds release decisions.

Starting Monitoring

Step 1: Select a Project

1. Click the Scope field or drag a folder onto the app
2. Select your project's root directory
3. The path will appear in the Scope selector

Step 2: Launch Guardian

Once you have:

• Selected a valid project path
• Configured your AI provider
• Signed in with GitHub (device authorization, if required)

Click Launch Guardian to start monitoring.

How Monitoring Works

Guardian watches your project for file changes and analyzes code using your configured AI provider:

1. File Detection: Monitors for saved changes in your project
2. Batch Processing: Groups changes for efficient analysis
3. AI Analysis: Sends code to your configured AI provider for review
4. Results Display: Shows findings and release impact in the activity panel

Release Decision Surface

Guardian translates findings into release-oriented outcomes:

• PASS
• PASS_WITH_WARNING
• BLOCK_UNTIL_APPROVED
• OVERRIDDEN (with required reason)

This prevents "we suggested a fix" from being treated as automatic release approval.

Snapshot Hydration

If Guardian restarts or reconnects, it now hydrates the monitor view from the local snapshot (.guardian/critiques.json) before merging live updates. This prevents empty dashboards when there are existing findings in the workspace.

Scan Scope Profiles

Guardian includes three scan profiles so you can balance cost vs coverage.

You can change this in Settings > General > Scan Scope. Profile changes apply the next time you start monitoring.

Tip: If you feel Guardian is "wasting tokens" on the wrong file types, keep the profile on Source and only use Extended/Full when you explicitly need them.

Understanding Findings

Severity Levels

Governance-Oriented Categories

Guardian prioritizes categories that affect release safety:

• Security Hygiene: Vulnerabilities, exposed secrets, unsafe auth/data handling
• Architecture Drift: Boundary violations, layering breaks, coupling regressions
• Quality Guardrails: Missing tests around risky changes, unsafe refactor patterns
• AI-Heavy Risk Signals: Large/suspicious AI-assisted changes requiring stricter human gate

Working with Findings

Viewing Details

Click any finding to see:

• Description of the issue
• Affected file and location
• Suggested fix (if available)

Applying Fixes

If a finding includes a proposed fix, you'll see a FIX action:

1. Expand the finding to review the proposed content
2. Click FIX (or APPLY THIS FIX) to write the updated file
3. Use Guru to sanity-check the result and decide whether to keep or revert the change

Ask Guru

Click the Ask Guru action (bot icon) on a finding to get:

• Detailed explanation of the issue
• Alternative solutions
• Best practice recommendations

Stopping Monitoring

Click Kill Guardian to stop monitoring:

• All file watchers are stopped
• Pending analyses are cancelled
• The app returns to idle state

Activity Panel

The activity panel shows:

• Real-time monitoring status
• Recent findings with severity
• Guru conversation history
• Applied fixes log

Chat History

Guardian maintains chat history per project:

• Conversations persist across sessions
• Clear history via the chat panel
• Export conversations as needed

Troubleshooting

Best Practices

1. Start Small: Begin with a focused directory
2. Review Before Apply: Always review suggested fixes
3. Use Guru: Ask for explanations on unclear findings
4. Monitor Costs: Track AI provider usage for paid APIs
5. Ignore Noise: Focus on high-severity issues first