# How AI-DLC Audit Logging Captures AI Responses with Timestamps

> Discover how AI-DLC audit logging records AI responses with ISO-8601 timestamps in an immutable audit.md file for a robust compliance trail.

- Repository: [Amazon Web Services - Labs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows)
- Tags: how-to-guide
- Published: 2026-05-09

---

**AI-DLC audit logging creates a single, append-only [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md) file in the `aidlc-docs/` directory that records every AI response with an ISO-8601 timestamp immediately after generation, ensuring an immutable compliance trail.**

The `awslabs/aidlc-workflows` repository implements a strict audit mechanism designed to guarantee that every interaction between users and AI systems is permanently recorded. AI-DLC audit logging enforces real-time capture of AI responses using standardized timestamps to maintain tamper-evident records for compliance analysis and post-run debugging.

## Core Architecture of the Audit Log

The system maintains **one centralized audit log** per workflow run. According to the architecture specification in [`scripts/aidlc-evaluator/ARCHITECTURE.md`](https://github.com/awslabs/aidlc-workflows/blob/main/scripts/aidlc-evaluator/ARCHITECTURE.md) (lines 12-13), the executor automatically creates an `aidlc-docs/` folder at the start of the first stage. Inside this directory, the workflow initializes an **append-only** [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md) file that serves as the definitive record of the entire session.

The [`docs/GENERATED_DOCS_REFERENCE.md`](https://github.com/awslabs/aidlc-workflows/blob/main/docs/GENERATED_DOCS_REFERENCE.md) (lines 10-12) confirms that this file captures *all* user inputs and AI responses without exception. The design explicitly forbids summarization or modification of logged content, ensuring the raw text of every AI-generated response is preserved exactly as produced.

## Mandatory Log Format and Timestamp Standards

Every entry written to [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md) must follow a strict structural template defined in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) (lines 86-94). The specification requires five mandatory fields for each interaction:

- **Stage name** – Identifies the current workflow phase (e.g., "Requirements Analysis")
- **Timestamp** – Records when the interaction occurred
- **User Input** – The exact prompt or query submitted
- **AI Response** – The complete, unaltered text generated by the AI
- **Context** – Describes the specific activity within the stage

The timestamp format follows strict **ISO-8601** standards (`YYYY-MM-DDTHH:MM:SSZ`) as mandated in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) (lines 83-85). This universal format ensures timezone-aware precision and compatibility with compliance auditing tools.

## Real-Time Capture Workflow

The [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) (lines 77-80) mandates that logging occurs **before the next user prompt** is accepted. This timing requirement ensures that no AI response can be lost or modified between generation and persistence. The execution flow follows this immutable sequence:

1. The executor agent loads the relevant stage rule file (e.g., [`inception/requirements-analysis.md`](https://github.com/awslabs/aidlc-workflows/blob/main/inception/requirements-analysis.md))
2. The AI generates a response based on user input
3. The executor immediately formats the entry with the current UTC timestamp
4. The system appends the block atomically to [`aidlc-docs/audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/audit.md) using the sandboxed `append_file` operation

Because the workflow engine itself—not the LLM—generates the timestamp using `datetime.now(timezone.utc)`, the recorded time reflects the exact moment the response was committed to the audit trail, not when the model finished its internal token generation.

## Implementation Example

The following Python pattern demonstrates how the executor implements the audit logging specification using the sandboxed `append_file` tool:

```python
from datetime import datetime, timezone

def log_ai_response(stage: str, user_input: str, ai_response: str, context: str):
    """Append a structured audit entry to aidlc-docs/audit.md."""
    timestamp = datetime.now(timezone.utc).isoformat(timespec='seconds')
    
    entry = (
        f"## [{stage}]\n"

        f"**Timestamp**: {timestamp}\n"
        f"**User Input**: \"{user_input}\"\n"
        f"**AI Response**: \"{ai_response}\"\n"
        f"**Context**: {context}\n"
        f"---\n"
    )
    
    # Atomic append via sandboxed tool (never overwrites)

    append_file("aidlc-docs/audit.md", entry)

```

This produces markdown output matching the specification exactly:

```markdown

## [Requirements Analysis]

**Timestamp**: 2026-05-09T14:45:12Z
**User Input**: "Generate a non-functional requirement for latency < 100 ms."
**AI Response**: "The system shall respond to any calculation request within 100 ms..."
**Context**: Requirements Analysis – NFR draft
---

```

## Summary

- **Single file location**: All audit data resides in [`aidlc-docs/audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/audit.md), created automatically when the workflow initializes
- **Append-only integrity**: The `append_file` operation guarantees immutable records by preventing overwrites or truncation
- **ISO-8601 compliance**: Timestamps use the strict format `YYYY-MM-DDTHH:MM:SSZ` for universal compatibility
- **Immediate persistence**: AI responses are logged atomically before any subsequent user interaction, eliminating data loss risk
- **Five-field structure**: Every entry contains Stage, Timestamp, User Input, AI Response, and Context

## Frequently Asked Questions

### What file format does AI-DLC use for audit logging?

AI-DLC uses a **markdown-based [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md) file** stored in the `aidlc-docs/` directory. The format utilizes markdown headers for stage names and bold text for field labels, making the log human-readable while maintaining strict structural consistency for automated parsing.

### Where is the audit log stored in an AI-DLC run?

The audit log resides at [`aidlc-docs/audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/audit.md) within the specific run's workspace folder. As documented in [`scripts/aidlc-evaluator/ARCHITECTURE.md`](https://github.com/awslabs/aidlc-workflows/blob/main/scripts/aidlc-evaluator/ARCHITECTURE.md), this location is standardized across all workflow instances to enable consistent tooling and compliance verification.

### What timestamp standard does AI-DLC require for compliance?

AI-DLC mandates **ISO-8601 format** with second-level precision in UTC (e.g., `2026-05-09T14:23:07Z`). This standard is enforced by the workflow rules defined in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) to ensure timezone-aware, unambiguous temporal records suitable for regulatory audits.

### How does AI-DLC prevent tampering with audit logs?

The system leverages an **append-only write mechanism** via the sandboxed `append_file` tool, which physically prevents overwriting or truncating existing content. Because the workflow engine controls the timestamp generation and file operations—not the LLM—the audit trail remains tamper-evident and cryptographically trustworthy for compliance purposes.