How AI-DLC Performs Content Validation for ASCII Art: Rules and Validation Logic

AI-DLC enforces strict content validation for ASCII art through a four-step checklist—checking line-width consistency, character sets, spacing, and corner alignment—before any diagram is written to documentation.

The AI-DLC (AWS Internal Documentation Lifecycle Control) framework ensures that all ASCII diagrams generated within the awslabs/aidlc-workflows repository meet strict formatting standards. This validation prevents malformed diagrams from breaking documentation rendering across different platforms and tools.

Content Validation Trigger Points

Content validation is invoked automatically whenever a rule step creates a file that may contain an ASCII diagram. According to the source code in aidlc-rules/aws-aidlc-rules/core-workflow.md, the workflow explicitly calls the content-validation rules defined in common/content-validation.md at specific pipeline stages【4†L52-L56】.

This trigger occurs before final file writes, ensuring that no invalid diagrams reach the output stage. The validation step is mandatory and cannot be bypassed during standard workflow execution.

ASCII Diagram Standards and Rules

The validator loads the ASCII Diagram Standards document from aidlc-rules/aws-aidlc-rule-details/common/ascii-diagram-standards.md before performing any checks【5†L11-L12】. This file defines the canonical requirements for all diagrams.

Allowed Characters and Line-Width Rules

The standards document specifies a restricted character set for portability. Valid diagrams may only use:

• Structural characters: +, -, |
• Directional arrows: ^, v, <, >
• Whitespace: Spaces only (tabs are forbidden)

Additionally, the character-width rule mandates that every line in a box must have exactly the same length【5†L15-L17】. This ensures proper alignment when rendered in monospace fonts.

Step-by-Step Validation Checks

The validator executes four specific checks as documented in aidlc-rules/aws-aidlc-rule-details/common/content-validation.md:

1. Line-width consistency – The validator counts characters on every line; if any line length differs from the others, validation fails immediately【6†L13-L14】.

2. Character set validation – Every character is verified against the permitted set. Any Unicode box-drawing glyphs or other non-ASCII symbols cause automatic rejection【6†L14-L15】.

3. Spacing verification – Tabs are strictly prohibited; only space characters are allowed for alignment purposes【6†L16-L17】.

4. Corner alignment – The validator tests that + corners line up vertically when rendered in a monospace font, ensuring structural integrity【5†L108-L112】.

Validation Failure Handling and Fallbacks

When validation passes, the diagram is inserted directly into the target Markdown file. However, if any check fails, AI-DLC implements a graceful degradation strategy:

• The system logs the specific validation error for debugging
• It falls back to a plain-text description of the diagram
• The workflow continues without writing the malformed ASCII art to the file【6†L72-L78】

This approach prevents broken diagrams from corrupting documentation while maintaining workflow continuity.

Audit Logging and Compliance

All validation attempts—both successes and failures—are recorded in audit.md as part of the mandatory audit trail【4†L84-L90】. This creates a complete historical record of content validation decisions, enabling compliance verification and debugging of diagram generation issues.

Implementation Example

The validation logic follows a structured pattern. Below is a simplified Python-style pseudocode that mirrors the AI-DLC implementation:

def validate_ascii_diagram(diagram: str) -> bool:
    # Load the allowed character set

    allowed = set("+-|^v<> ")
    lines = diagram.splitlines()

    # 1️⃣ Ensure every line has the same length

    line_lengths = {len(line) for line in lines}
    if len(line_lengths) != 1:
        return False

    # 2️⃣ Check for forbidden Unicode characters

    if any(ch not in allowed for ch in diagram):
        return False

    # 3️⃣ Verify spaces only (no tabs)

    if any("\t" in line for line in lines):
        return False

    # 4️⃣ Confirm corners line up (simple corner check)

    top = lines[0]
    bottom = lines[-1]
    if not (top.startswith("+") and top.endswith("+") and
            bottom.startswith("+") and bottom.endswith("+")):
        return False

    return True

This logic reflects the actual rule definitions found in the aidlc-rules/aws-aidlc-rule-details/common/ directory.

Summary

• AI-DLC content validation triggers automatically before writing files containing ASCII art, as defined in aidlc-rules/aws-aidlc-rules/core-workflow.md.
• Strict character standards allow only + - | ^ v < > and spaces, prohibiting Unicode box-drawing characters and tabs.
• Line-width consistency is mandatory; every line in a diagram must contain the exact same number of characters.
• Graceful degradation ensures that validation failures log errors and fall back to plain text rather than breaking the workflow.
• Complete audit trails in audit.md record every validation decision for compliance and debugging purposes.

Frequently Asked Questions

What characters are permitted in AI-DLC ASCII diagrams?

AI-DLC allows only specific ASCII characters for diagram construction: plus signs (+), hyphens (-), vertical bars (|), directional arrows (^, v, <, >), and space characters. Unicode box-drawing glyphs and tab characters are explicitly forbidden according to ascii-diagram-standards.md【5†L15-L17】.

How does AI-DLC handle validation failures?

When validation fails, AI-DLC logs the specific error, substitutes a plain-text description of the intended diagram, and continues the workflow without writing the malformed ASCII art. This ensures documentation generation never halts due to formatting issues【6†L72-L78】.

Where is the validation logic defined in the codebase?

The validation rules reside in aidlc-rules/aws-aidlc-rule-details/common/content-validation.md, while the triggering mechanism is defined in aidlc-rules/aws-aidlc-rules/core-workflow.md. The character set specifications live in aidlc-rules/aws-aidlc-rule-details/common/ascii-diagram-standards.md【4†L52-L56】【5†L11-L12】.

Why does AI-DLC require strict line-width consistency?

The character-width rule ensures that all lines in a box have exactly the same length, guaranteeing proper alignment when diagrams are rendered in monospace fonts across different platforms and documentation viewers【5†L15-L17】. This prevents visual corruption in terminal displays and code editors.

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