Reviews & Fix Proposals

Overview

Reviews & Fix Proposals provide a lightweight queue for previewing and applying fixes in a controlled way. Guardian reads proposals from your workspace at:

.guardian-proposals/fix_proposals.jsonl

A proposal is a JSONL record that contains the FULL updated file content (not a patch/diff). You can generate proposals from your own tooling, or copy/paste Guru output into a proposal entry.

How It Works

1. Append proposal records to .guardian-proposals/fix_proposals.jsonl
2. Open Reviews to browse and preview proposals
3. Click Request Review to write the proposed content to disk and verify it in Guru
4. Mark the outcome as Applied or Rejected

Accessing Reviews

Click the Reviews tab in the left sidebar to open the review queue.

Proposal Lifecycle

Status States

Pending ──► Review Requested ──► Applied
    │
    └──────► Rejected

Status	Description
Pending	New proposal, not yet reviewed
Review Requested	Proposed content was written to disk and awaits confirmation
Applied	Marked as applied
Rejected	Marked as rejected

Taking Action

Request Review

When you want Guardian to apply the proposal and then verify it in chat:

1. Select the proposal
2. Click Request Review
3. Guardian writes the proposal's proposed_content to the target file
4. The proposal moves to Review Requested and Guru opens for verification

Mark Applied

When you're satisfied with the result:

1. Confirm the file looks correct
2. Click Mark Applied to finalize the status

Reject

When the proposal isn't appropriate:

1. Click Reject
2. The proposal moves to Done with Rejected status

Proposal Format

Required Fields

Each JSONL proposal must include:

• proposal_id
• timestamp
• file_path
• proposed_content (FULL updated file content)

Optional fields supported by the UI:

• finding_id
• suggestion
• reasoning
• confidence
• proposed_by
• original_content_hash

Minimal Example

{
  "proposal_id": "p-1700000000-1",
  "timestamp": "2026-02-17T12:00:00Z",
  "file_path": "src/example.ts",
  "proposed_content": "/* FULL UPDATED FILE CONTENT HERE */\n"
}

Storage

Fix proposals are stored in your workspace:

.guardian-proposals/
└── fix_proposals.jsonl

• Append-only log format
• Human-readable JSON Lines
• Survives app restarts
• Can be version controlled (optional)

Best Practices

1. Start with the highest-impact files first (auth, payments, build/deploy surfaces)
2. Always request full-file output from Guru (no diff markers, no markdown)
3. Run tests after applying changes
4. Reject and regenerate proposals when the underlying file changed significantly

Troubleshooting

Issue	Solution
No proposals showing	Confirm .guardian-proposals/fix_proposals.jsonl exists and contains valid JSONL records
Proposal missing proposed_content	Ensure proposed_content contains the full updated file, not a diff
Can't request review	Check file permissions and confirm the target file path is correct
UI not updating	Click Refresh or restart the app (proposals are preserved)

Coming Soon

• Batch operations: apply/reject multiple proposals at once
• Review templates: save common rejection reasons