Living Audits

Definition

Living Audits are markdown documents in _AUDIT/ that track the current health of your project across multiple dimensions. Unlike static documentation that becomes stale, these documents are automatically updated by specialized agents during audits.

Each audit document follows a consistent format: metadata, open items, and audit history. When an issue is resolved, it's removed from open items (not marked complete). The history table preserves what was done and when.

Philosophy

In farming, you don't keep a list of last year's weeds. You track current problems that need attention. Living audits work the same way - they're a dashboard of what needs attention now, not a growing archive of everything ever found.

Benefits of Living Documentation

• Always current - no manual sync needed
• Quick health check at any time
• Clear priority through open items count
• Historical context without clutter
• Trackable scores over time

Audit Documents

Farmwork creates three audit documents during initialization. Earlier versions spread findings across eight separate files (SECURITY.md, PERFORMANCE.md, ACCESSIBILITY.md, CODE_QUALITY.md, TESTS.md, and more) - v2.0.0 consolidates all of that into the code-reviewer agent's findings, reported directly rather than scattered across documents:

Standard Format

All audit documents follow a consistent structure:

# Farmhouse

**Last Updated:** 2024-01-15
**Score:** 8/10
**Status:** 3 open items

---

## Open Items
*Remove items when resolved - don't mark complete*

### HIGH: SQL Injection in search endpoint
**File:** src/api/search.ts:42
User input passed directly to query. Use parameterized queries.

### MEDIUM: Missing rate limiting on auth endpoints
**File:** src/api/auth.ts
Add rate limiting to prevent brute force attacks.

### LOW: Missing alt text on product images
**File:** src/components/ProductCard.tsx
Add descriptive alt attributes for screen readers.

---

## Audit History
| Date | Changes |
|------|---------|
| 2024-01-15 | Fixed XSS in comments, 3 items remaining |
| 2024-01-10 | Initial audit, found 4 issues |

Update Mechanism

Living audits are updated automatically during specific operations:

• /audit — Quick audit, updates FARMHOUSE.md
• /inspect — Deep audit via code-reviewer and code-cleaner, updates FARMHOUSE.md
• /push — Updates FARMHOUSE.md metrics during deployment
• Direct agent invocation — the-farmer or idea-gardener update their documents

Agents have Edit access to their respective documents and are instructed to follow the standard format. They add new issues, remove fixed ones, and update the history table.

FARMHOUSE.md

The FARMHOUSE.md is the central command center - a dashboard that aggregates open items and metrics for the whole project. Since v2.0.0 folds security, performance, quality, and accessibility review into a single code-reviewer agent, its findings land here instead of being scattered across separate files:

# Farmhouse

**Last Updated:** 2024-01-15

## Health Dashboard

| Area | Score | Open |
|------|-------|------|
| Code Review | 8/10 | 3 |

## Component Counts

- Agents: 4
- Commands: 1

## Ideas
- Garden: 5 fresh, 2 wilting
- Plans: 1 active