audit-goals

# audit-goals

Audit project goals by examining milestones and codebase evidence. Uses AI to determine whether each goal has been achieved based on documented progress.

## Usage

```bash
echo '{"project_name": "my-project", "goals_path": "/path/to/goals.md", "milestones_path": "/path/to/milestones.md", "project_dir": "/path/to/project"}' | audit-goals
```

### Input (JSON)

| Field | Required | Description |
|-------|----------|-------------|
| `project_name` | Yes | Display name for the project |
| `goals_path` | Yes | Absolute path to goals.md file |
| `milestones_path` | No | Absolute path to milestones.md file |
| `project_dir` | No | Project root for codebase exploration (defaults to cwd) |

## Expected File Formats

### goals.md

The goals file should have sections for Active, Future, and Non-Goals with checkbox items:

```markdown
## Active Goals

- [x] Implement user authentication
- [~] Add API rate limiting (in progress)
- [ ] Create admin dashboard

## Future Goals

- [ ] Mobile app support
- [ ] Multi-language support

## Non-Goals

- [ ] We will not build a native desktop app
- [ ] We will not support IE11
```

**Checkbox meanings:**
- `[x]` - Marked as complete
- `[~]` - Marked as in progress
- `[ ]` - Not started

Note: The tool verifies these against actual evidence - existing checkboxes may be outdated.

### milestones.md

The milestones file should document completed work:

```markdown
## Milestone 1: Authentication (Done)

- Implemented JWT-based auth
- Added login/logout endpoints
- Created user session management

## Milestone 2: API Foundation (Completed)

- REST API structure
- Error handling middleware
- Request validation
```

Mark milestones as "Done" or "Completed" to indicate they're finished.

## Output

Returns JSON with status for each goal:

```json
{
  "active": [
    {"text": "Implement user authentication", "status": "met", "priority": "high", "reason": "Milestone 1 shows JWT auth completed"}
  ],
  "future": [
    {"text": "Mobile app support", "status": "not_met", "priority": "medium", "reason": "No evidence of mobile work"}
  ],
  "non_goals": [
    {"text": "We will not build a native desktop app", "status": "met", "priority": "medium", "reason": "Project correctly avoids this"}
  ],
  "summary": {
    "active_met": 3,
    "active_partial": 1,
    "active_not_met": 0,
    "active_total": 4,
    "health": "GOOD"
  }
}
```

### Status Values

- `met` - Goal achieved (80%+ evidence)
- `partial` - Some work done but incomplete (20-80%)
- `not_met` - No evidence of implementation

### Health Values

- `COMPLETE` - All active goals met
- `GOOD` - Most goals met, minor gaps
- `NEEDS ATTENTION` - Several partial/unmet goals
- `CRITICAL` - Major goals unmet

## Example

```bash
# Audit development-hub project
echo '{
  "project_name": "Development Hub",
  "goals_path": "/home/user/projects/development-hub/docs/goals.md",
  "milestones_path": "/home/user/projects/development-hub/docs/milestones.md",
  "project_dir": "/home/user/projects/development-hub"
}' | audit-goals
```