How AI-DLC Audit Logging Captures AI Responses with Timestamps

AI-DLC audit logging creates a single, append-only 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 (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 file that serves as the definitive record of the entire session.

The 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 must follow a strict structural template defined in 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 (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 (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)
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 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:

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:

## [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, 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 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 within the specific run's workspace folder. As documented in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}