# File Audit Trail Reference

This document describes the file audit trail system used by ao-ops to track files created outside the `.agent/ops/` directory.

## Purpose

When preparing code for external review, ao-generated files create noise. The audit trail enables:

1. **Identification** — Know which files ao-ops created vs. user-created
2. **Clean branches** — `ao-selective-branch` can exclude logged files
3. **Transparency** — Clear record of what the agent touched

## Log Location

**Path:** `.agent/ops/log/created-files.log`

## Log Format

```
{ISO-8601-timestamp} {ACTION} {relative-path}
```

### Fields

| Field | Format | Example |
|-------|--------|---------|
| timestamp | `YYYY-MM-DDTHH:MM:SSZ` | `2026-01-20T10:15:32Z` |
| action | `CREATE` \| `MODIFY` \| `DELETE` | `CREATE` |
| path | Workspace-relative, forward slashes | `src/utils/helper.py` |

### Example Log

```
# ao-Ops File Creation Audit Trail
# --- Log entries below this line ---
2026-01-20T10:15:32Z CREATE docs/PLANNING.md
2026-01-20T10:16:45Z CREATE src/utils/helper.py
2026-01-20T11:30:00Z MODIFY src/main.py
2026-01-20T14:22:10Z CREATE tests/test_helper.py
2026-01-20T15:00:00Z DELETE docs/PLANNING.md
```

## What to Log

### MUST Log
- New source files (`src/`, `lib/`)
- New test files (`tests/`, `__tests__/`)
- New documentation outside `.agent/ops/docs/` (`docs/`, `README.md` at root)
- Configuration files added to project (`tsconfig.json`, `pyproject.toml`, etc.)
- Build scripts added (`scripts/build.py`, `Makefile`)

### DO NOT Log
- Files inside `.agent/ops/` — excluded by convention
- Files inside `.ao/skills/`, `.github/prompts/`, `.github/agents/` — excluded by convention
- Temporary files that will be deleted before commit
- Files explicitly requested by user in the same message

## Logging Commands

### PowerShell (Windows/Cross-platform)

```powershell
function Log-AgentFile {
    param(
        [string]$Action,  # CREATE, MODIFY, DELETE
        [string]$Path     # Relative path with forward slashes
    )
    $timestamp = (Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
    $logPath = ".agent/ops/log/created-files.log"
    Add-Content -Path $logPath -Value "$timestamp $Action $Path"
}

# Usage
Log-AgentFile -Action "CREATE" -Path "src/utils/helper.py"
```

### Bash (Linux/macOS)

```bash
log_agent_file() {
    local action="$1"  # CREATE, MODIFY, DELETE
    local path="$2"    # Relative path
    local timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
    echo "$timestamp $action $path" >> .agent/ops/log/created-files.log
}

# Usage
log_agent_file "CREATE" "src/utils/helper.py"
```

### Agent Pattern (Inline)

When an agent creates a file, append to log immediately after:

```
# After creating src/new-module.py
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) CREATE src/new-module.py" >> .agent/ops/log/created-files.log
```

## Skills That Should Log

| Skill | When to Log |
|-------|-------------|
| `ao-implementation` | When creating/modifying source or test files |
| `ao-testing` | When creating new test files |
| `ao-docs` | When creating docs outside `.agent/ops/docs/` |
| `ao-create-skill` | When creating skill files (in `.ao/skills/`) — NO, excluded by convention |
| `ao-planning` | When creating planning docs outside `.agent/ops/` |

## Integration with selective-branch

The `ao-selective-branch` skill reads this log to identify files to exclude:

```powershell
# Read logged files
$loggedFiles = Get-Content ".agent/ops/log/created-files.log" | 
    Where-Object { $_ -match "^\d{4}-\d{2}-\d{2}" } |
    ForEach-Object { ($_ -split " ", 3)[2] }

# Present to user
Write-Host "ao-ops created these files outside .agent/ops/:"
$loggedFiles | ForEach-Object { Write-Host "  - $_" }
```

## Log Maintenance

### Clearing the Log

After a clean branch is created or work is merged:

```powershell
# Keep header, remove entries
$header = Get-Content ".agent/ops/log/created-files.log" | Select-Object -First 12
$header | Set-Content ".agent/ops/log/created-files.log"
```

### Archiving

For long-running branches, consider archiving periodically:

```powershell
$date = Get-Date -Format "yyyy-MM-dd"
Copy-Item ".agent/ops/log/created-files.log" ".agent/ops/log/created-files-$date.log"
```

## Git Considerations

### Should the log be committed?

**Recommended: Yes, commit the log.**

- Provides audit trail for reviewers
- Survives branch switches
- Can be compared across branches

### .gitignore

Do NOT add `.agent/ops/log/created-files.log` to `.gitignore`.

However, archived logs can be ignored:
```
.agent/ops/log/created-files-*.log
```
