Audit Trail

[!WARNING] Status: Planned. The structured audit trail is part of the governance layer currently under development. Today, Agent Traces capture per-file contribution records. The design below describes the planned full audit system.

The Audit Trail will serve as the immutable record of all decisions in your software factory — not just what changed, but why and by whom. It is a core component of the ChooChoo Architecture and will feed into compliance reporting.

Decision Traces

A Decision Trace links the following:

• Actor: The Agent or Human who initiated the change.
• Artifact: The file being changed (versioned). This could be a Product, Contract, or Workflow.
• Policy: The rule that authorized (or required approval for) the change.
• Reasoning: The agent's internal Chain-of-Thought (captured via Agent Trace) or the human's comment.
• Outcome: Approved, Rejected, or Auto-Applied — determined by the risk score.

Each trace also records the agent's System Card reference, providing full traceability from action to identity.

Log Schema

{
  "traceId": "trace_2026-01-31_abc123",
  "timestamp": "2026-01-31T14:00:00Z",
  "action": "update",
  "actor": {
    "type": "agent",
    "id": "cursor-agent-001",
    "systemCard": "system-cards/cursor.yaml"
  },
  "change": {
    "description": "Added phone_number field",
    "diff": "+ - name: phone_number\n+   type: string\n+   pii: true"
  },
  "riskScore": 3.6,
  "approvals": [
    {
      "approver": "[email protected]",
      "timestamp": "2026-01-31T15:30:00Z"
    }
  ]
}

The riskScore field is computed by ChooChoo's risk scoring algorithm and determines whether the change was auto-approved or required human approval. The actor.systemCard references the agent's System Card for full transparency.

Querying the Audit Trail

You can query the audit trail using the choochoo agent audit command to view activity for a specific agent, or through The Station UI for full-text search and visualization.

# View audit history for a specific agent
choochoo agent audit cursor-agent-001

# View all recent traces
choochoo trace list

See the CLI Reference for all available commands and output formats.

Retention & Integrity

• Retention: Default retention is 7 years (2555 days) to satisfy SOX and HIPAA requirements. Configure this via the governance.auditRetentionDays setting in .choochoorc.
• Integrity: Logs are append-only and should be stored in write-once-read-many (WORM) storage in production environments. See Security Considerations for encryption and signature requirements.

Each audit entry includes a cryptographic signature to verify authenticity and prevent tampering. Audit logs should be stored separately from operational data — this is enforced by the security model.

Integration with Compliance

The Audit Trail is the primary data source for Compliance Reporting. When generating reports for frameworks like GDPR, SOX, or HIPAA, ChooChoo queries the trail filtered by:

• Compliance tags on modified fields
• Date ranges specified by the auditor
• Agent or human actor identity

Emergency override events from Approval Workflows are flagged with the highest severity and appear prominently in all compliance reports.

Audit Trail in CI/CD

In CI/CD pipelines, every choochoo validate run generates audit entries. The exit codes returned by the CLI correspond to specific audit events:

• Exit 0 — Validation passed, auto-approved trace recorded.
• Exit 10 — Approval required, pending trace recorded.
• Exit 11 — Approval rejected, rejection trace recorded with reason.

Related