How AI-DLC Audit Logging Captures User Inputs: A Complete Technical Guide

AI-DLC audit logging captures every user input through mandatory logging hooks defined in the core workflow rules, appending timestamped entries to an immutable audit.md file with strict append-only enforcement.

The AI-DLC (AI-Driven Development Life-Cycle) framework in the awslabs/aidlc-workflows repository guarantees a complete, tamper-evident record of every interaction between human programmers and AI agents. This is achieved through a dedicated audit log that is automatically updated at each mandatory logging point defined in the workflow rules, ensuring comprehensive AI-DLC audit logging throughout the development lifecycle.

Mandatory Logging Hooks in the Core Workflow

Every stage of the AI-DLC workflow contains explicit "MANDATORY: Log … in audit.md" directives defined in aidlc-rules/aws-aidlc-rules/core-workflow.md. These hooks ensure that no user input is processed without immediate recording.

The Workspace Detection stage requires logging the initial request (lines 100-101 of core-workflow.md). This pattern repeats across Requirements Analysis, User Stories, Workflow Planning, Application Design, and all construction stages. Each step that receives user-provided text is captured before any AI processing proceeds, creating an unbroken chain of accountability.

Audit Log Structure and Format

The audit file audit.md lives under the generated aidlc-docs/ folder, with its purpose documented in aidlc-rules/aws-aidlc-rule-details/common/terminology.md as the "complete audit trail of all interactions."

Each log entry follows a strict structure:

• Timestamp – ISO-8601 format in UTC, added by the AI runtime
• User Input – The raw string exactly as typed by the user, never summarized
• AI Response – The complete output generated by the agent for that step

A real-world example of this format appears in scripts/aidlc-evaluator/test_cases/all-stages/golden-aidlc-docs/aidlc-docs/audit.md, demonstrating how entries accumulate during a full workflow run.

Append-Only Enforcement and Integrity

The core workflow rules explicitly forbid overwriting audit.md. All writes must be append-only, as noted in the "CRITICAL" sections of the workflow documentation. This architectural constraint guarantees chronological integrity and prevents accidental loss or deliberate modification of prior entries.

Because the execution engine runs inside the AI-DLC sandbox, it can ensure that no external process modifies the file. The append-only policy means historical entries remain immutable once written, creating a forensic-quality record suitable for compliance audits and security reviews.

Execution Engine Integration

The execution engine (scripts/aidlc-evaluator/packages/execution/README.md) handles the technical implementation of AI-DLC audit logging. The engine reads the current audit.md, concatenates the new entry, and writes the combined content back to disk.

This integration ensures that logging occurs atomically with stage execution. The engine manages file locking and encoding (UTF-8) to prevent corruption during concurrent operations, maintaining the integrity of the audit trail even during complex, multi-stage workflows.

Practical Implementation Example

The following Python snippet demonstrates how a stage records user input and appends it to audit.md. While simplified, this illustrates the same pattern the production AI-DLC engine uses internally.

import datetime
from pathlib import Path

AUDIT_PATH = Path("aidlc-docs/audit.md")

def append_audit(timestamp: str, user_input: str, ai_response: str, context: str):
    """Append a single audit entry to audit.md."""
    entry = (
        f"## {context}\n"

        f"**Timestamp**: {timestamp}\n"
        f"**User Input**: \"{user_input}\"\n"
        f"**AI Response**: {ai_response}\n"
        "\n---\n\n"
    )
    # Append-only – do not truncate the file

    with AUDIT_PATH.open("a", encoding="utf-8") as f:
        f.write(entry)

# Example usage inside a stage:

if __name__ == "__main__":
    ts = datetime.datetime.utcnow().isoformat() + "Z"
    user_prompt = "Add JWT authentication to the service."
    ai_reply = "Generated auth middleware and updated the config."
    append_audit(ts, user_prompt, ai_reply, "INCEPTION - Requirements Analysis")

Key implementation details:

• The timestamp is generated at runtime using datetime.utcnow().
• User prompts are recorded exactly as-typed, preserving punctuation and formatting.
• The file opens in append mode ("a"), ensuring existing content is never truncated.

Summary

• AI-DLC audit logging captures every user interaction through mandatory hooks defined in core-workflow.md.
• The audit trail resides in aidlc-docs/audit.md with entries containing raw user inputs, AI responses, and UTC timestamps.
• Strict append-only enforcement prevents tampering and ensures chronological integrity.
• The execution engine manages atomic writes to maintain forensic-quality records.
• All generated documentation, including audit logs, can be exported for compliance audits or integrated into CI/CD security checks.

Frequently Asked Questions

What file format does AI-DLC audit logging use?

AI-DLC audit logging uses a Markdown file named audit.md stored in the aidlc-docs/ directory. The format uses standard Markdown headers for entry separation and bold text for metadata fields, making it human-readable while remaining machine-parseable for automated compliance checks.

Does AI-DLC audit logging capture raw or summarized user inputs?

According to the terminology document in aidlc-rules/aws-aidlc-rule-details/common/terminology.md, AI-DLC audit logging captures the raw string exactly as the user typed it. The framework explicitly forbids summarization or paraphrasing at the logging stage to ensure complete forensic accuracy.

How does AI-DLC prevent tampering with audit logs?

The prevention mechanism relies on append-only file operations enforced by the execution engine. The workflow rules contain "CRITICAL" directives that prohibit overwriting audit.md, and the engine runs inside a sandboxed environment that prevents external processes from modifying the file. This creates a tamper-evident chronological record.

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

The audit log is stored at aidlc-docs/audit.md relative to the project root. This location is generated automatically when the workflow initializes, and the path is consistently referenced across all mandatory logging hooks in aidlc-rules/aws-aidlc-rules/core-workflow.md.

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