How AI-DLC Checkbox Enforcement Tracks Plan Execution Progress

AI-DLC enforces a strict two-level checkbox tracking system that requires the AI to mark tasks as complete in the same interaction where work is performed, creating an immutable, audit-ready record of every development step.

The awslabs/aidlc-workflows repository implements AI-DLC checkbox enforcement as a foundational mechanism for transparent AI-driven development. By mandating real-time updates to Markdown task lists across both granular plan files and high-level stage trackers, the system ensures that every action remains visible and verifiable. This approach binds checkbox state changes directly to work completion, preventing progress drift while generating tamper-proof documentation.

The Two-Level Checkbox Architecture

AI-DLC utilizes a hierarchical tracking system that operates at both the micro and macro levels of a development lifecycle.

Plan-Level Checkboxes

Each workflow stage—such as Inception, Construction, or Operations—contains dedicated Markdown plan files that decompose work into granular, actionable steps. Files like construction/code-generation.md represent every sub-task as a Markdown checkbox ([ ]). When the AI executes a specific step, it must immediately update the same file, converting the marker to [x] to indicate completion.

This update must occur in the same interaction that performed the actual work. The requirement is absolute: no step can be considered finished until its corresponding checkbox reflects the completed state in the plan document.

Stage-Level Progress Tracking

For high-level visibility, aidlc-state.md serves as the master progress tracker. This file maintains a checklist of major phases, indicating which stages have been started, completed, or skipped. After the AI finishes all granular tasks within a stage, it updates aidlc-state.md to reflect the phase transition, providing users with a quick visual summary of the entire pipeline without requiring them to parse individual plan files.

Mandatory Enforcement Rules

The core workflow defined in aidlc-rules/aws-aidlc-rules/core-workflow.md establishes non-negotiable rules under the section "MANDATORY: Plan-Level Checkbox Enforcement". The specification states:

• Never complete any work without updating the plan checkboxes.
• Immediately after completing any step, mark that step [x].
• The update must be performed in the same interaction where the step was executed.

These constraints are reinforced throughout the rule set, appearing in files such as inception/user-stories.md and the common terminology guide. This distributed reinforcement ensures that the AI cannot bypass the tracking mechanism regardless of which development phase is active.

Audit Logging and User Control

Beyond the checkbox updates themselves, AI-DLC implements safeguards to ensure accountability and user oversight.

Immutable Audit Trails

Every checkbox modification generates an entry in audit.md, creating a tamper-proof record of progress. Each log entry includes a precise timestamp, the raw user input that triggered the change, and the specific context of the update.

Explicit User Approval

Following each checklist update, the AI presents a standardized two-option completion prompt requiring explicit user consent before proceeding. The interface offers "Request Changes" or "Continue to Next Stage", ensuring that checkbox state always reflects verified user intent rather than unilateral AI decisions.

Real-World Execution Example

The AI follows a strict five-step loop when processing plan files:

1. Load the relevant plan file and parse the next unchecked [ ] item.
2. Execute the described work (e.g., generate code, run tests).
3. Immediately edit the plan file, changing [ ] to [x] for the completed task.
4. Append an entry to audit.md documenting the change with timestamp and context.
5. Prompt the user with the two-option completion message to approve continuation.

Consider a Code Generation stage defined in construction/code-generation.md:

# construction/code-generation.md

- [ ] **Planning** – Create detailed generation plan
- [ ] **Generation** – Generate source files
- [ ] **Tests** – Generate unit tests

After completing the Planning sub-step, the AI immediately transforms the file to:

# construction/code-generation.md

- [x] **Planning** – Create detailed generation plan
- [ ] **Generation** – Generate source files
- [ ] **Tests** – Generate unit tests

Simultaneously, the system records the action in audit.md:

## Code Generation – Planning Completed

**Timestamp**: 2026-05-09T14:32:10Z  
**User Input**: "Approve the code‑generation plan"  
**AI Response**: "✅ Planning step marked complete."  
**Context**: Updated checkbox in construction/code-generation.md

The AI then displays the completion prompt:

✅ Planning step complete.  
Do you want to **Request Changes** or **Continue to Next Stage**?

Summary

• AI-DLC checkbox enforcement operates through a two-level system tracking both granular tasks in plan files and high-level stages in aidlc-state.md.
• The core-workflow.md file mandates that checkbox updates occur in the same interaction as work completion, with zero tolerance for delayed updates.
• Every checkbox change is permanently logged in audit.md with timestamps and user input context.
• Users maintain control through mandatory two-option approval prompts before workflow progression.
• This architecture ensures transparent, reproducible records of every action taken during the AI-driven development lifecycle.

Frequently Asked Questions

What happens if the AI doesn't update checkboxes immediately?

The aidlc-rules/aws-aidlc-rules/core-workflow.md specification explicitly forbids completing work without simultaneous checkbox updates. If the AI attempts to report a task as finished without modifying the corresponding [ ] to [x] in the same interaction, the workflow violates its mandatory enforcement rules, effectively making the completion invalid within the AI-DLC framework.

Where is the high-level progress tracked in AI-DLC?

High-level progress resides in aidlc-state.md, which maintains a bird's-eye view of stage completion across the entire lifecycle. While individual plan files like construction/code-generation.md track granular sub-tasks, aidlc-state.md reflects whether entire phases (Inception, Construction, Operations) have been initiated, completed, or skipped.

How does AI-DLC prevent tampering with progress records?

The framework maintains an immutable audit log in audit.md that records every checkbox state change with precise timestamps and the exact user input that triggered the update. This creates a cryptographically-adjacent chain of evidence where each modification is permanently associated with its triggering context, making retroactive tampering detectable.

Can users override checkbox states manually?

While users provide explicit approval through the two-option prompts ("Request Changes" or "Continue to Next Stage"), the checkbox updates themselves are performed by the AI during task execution. Users guide the workflow through approval decisions rather than direct Markdown manipulation, ensuring that the AI remains accountable for accurate status reporting while users retain veto power over progression.

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