# DES Audit Trail

Immutable audit logs for nWave workflow traceability.

## Structure

- `audit-YYYY-MM-DD.log`: JSONL format with daily rotation
- Append-only (no modifications to existing entries)
- SHA256 content hashing for immutability verification

## Schema

Each audit event is a JSON object with these fields:

| Field | Type | Description |
|-------|------|-------------|
| `event` | string | Event type (see Events Logged) |
| `timestamp` | string | ISO 8601 UTC timestamp |
| `feature_name` | string | Project/feature identifier (e.g., `"audit-log-refactor"`) |
| `step_id` | string | Step identifier within the feature (e.g., `"03-02"`) |
| `phase_name` | string | TDD phase name (for phase events) |
| `data` | object | Additional event-specific data |

### Schema Version

**Current**: v2.0 - Uses `feature_name` and `step_id` as direct fields.

**Migration from v1.x**: The previous schema used a single `step_path` field containing a file path
(e.g., `"docs/feature/my-feature/steps/03-02.yaml"`). In v2.0, this was replaced with semantic
fields `feature_name` and `step_id` that are decoupled from file system layout.

To migrate queries from v1.x to v2.0:
- Replace `.step_path` with `.feature_name` and/or `.step_id`
- Replace path-based filtering with field-based filtering

## Events Logged

- `TASK_INVOCATION_STARTED`: Agent execution begins
- `TASK_INVOCATION_VALIDATED`: Pre-invocation hooks passed
- `PHASE_STARTED`: TDD phase begins (e.g., RED_UNIT, GREEN, REFACTOR)
- `PHASE_COMPLETED`: TDD phase finishes
- `SCOPE_VIOLATION`: File modified outside declared scope
- `TIMEOUT_WARNING`: Phase execution exceeding threshold

## Query Examples

```bash
# Filter violations
grep '"event":"SCOPE_VIOLATION"' audit-*.log | jq .

# Count violations by feature
jq -r 'select(.event=="SCOPE_VIOLATION") | .feature_name' *.log | sort | uniq -c

# Count violations by step within a feature
jq -r 'select(.event=="SCOPE_VIOLATION" and .feature_name=="audit-log-refactor") | .step_id' *.log | sort | uniq -c

# View phase execution timeline
jq -r 'select(.event | startswith("PHASE_")) | "\(.timestamp) \(.feature_name) \(.step_id) \(.phase_name) \(.event)"' audit-*.log

# Filter all events for a specific feature
jq -r 'select(.feature_name=="audit-log-refactor")' audit-*.log

# Filter events for a specific step
jq -r 'select(.feature_name=="audit-log-refactor" and .step_id=="03-02")' audit-*.log
```

## Retention Policy

- Daily logs retained for 90 days
- Archive to `docs/evolution/audit-archive/` after 90 days
- No automatic deletion (manual cleanup only)
