How AI-DLC Enforces Extension Rules as Blocking Constraints

AI-DLC treats every enabled extension rule as a hard, non-negotiable constraint that blocks workflow progression until all verification criteria are satisfied, removing the "Continue" button and forcing issue resolution before the next stage can begin.

The awslabs/aidlc-workflows repository implements a strict governance model where extension rules function as quality gates. When the workflow engine initializes, it loads enabled extensions and treats every rule within them as a blocking requirement that must pass verification before the user can advance to subsequent stages.

Extension Loading and Opt-In Mechanism

The enforcement process begins with a selective loading system that distinguishes between optional and mandatory extensions.

Scanning the extensions/ Directory

At workflow startup, the engine scans the extensions/ directory and loads only files matching the *.opt-in.md pattern. These files contain prompts that explicitly ask whether the extension should be enabled. According to aidlc-rules/aws-aidlc-rules/core-workflow.md (lines 29–35), the engine lists all sub-directories under extensions/ and presents the opt-in prompt to the user.

When a user opts-in, the corresponding rule file is derived by stripping the .opt-in.md suffix. For example, selecting "Yes" for security-baseline.opt-in.md triggers the loading of security-baseline.md. The rule file remains unloaded until explicit confirmation occurs.

State Persistence

The enabled or disabled status for each extension is recorded in aidlc-docs/aidlc-state.md under the Extension Configuration section (core-workflow.md, lines 50–51). The runtime consults this state file before enforcing any rules, ensuring that only explicitly enabled extensions act as blocking constraints.

Extensions that lack a *.opt-in.md file are considered always-enabled and load immediately during initialization.

Declaring Rules as Blocking Constraints

All rule files explicitly declare their blocking status. In aidlc-rules/aws-aidlc-rule-details/extensions/security/baseline/security-baseline.md (lines 17–19), the document states: "All rules in this document are blocking by default." This declaration means that if any rule's verification criteria are not met, it constitutes a blocking finding that halts workflow progression.

This pattern is consistent across all extension types. Whether the extension covers security baselines, property-based testing, or compliance requirements, the rule files use identical language to establish blocking behavior. Any non-compliant rule triggers the blocking mechanism, while compliant rules allow normal progression.

Runtime Enforcement and UI Blocking

When a stage completes and prepares to present navigation options, the engine performs a three-step enforcement process for every applicable extension rule.

Compliance Evaluation

The runtime evaluates the rule's verification checklist against artifacts generated in the current stage. For example, a security rule checking for "Encryption at rest must be enabled" examines the generated infrastructure code for RDS instances or S3 buckets. The results populate a compliance summary table with three possible statuses: Compliant, Non-compliant, or N/A.

If any rule returns Non-compliant, the engine suppresses the "Continue to Next Stage" button and displays only a Request Changes option (core-workflow.md, lines 46–48). The UI presents a list of failing rule IDs, such as SECURITY-01, alongside specific remediation instructions.

Audit Logging

Every blocking finding is recorded in aidlc-docs/audit.md with the rule ID, description, timestamp, and stage context. This creates an immutable record of compliance failures and resolutions. The audit entry includes the user's input that triggered the check and the AI's response explaining the blocking condition.

Conditional Skipping for Non-Applicable Rules

Rules that do not apply to the current project scope are marked N/A rather than non-compliant. According to security-baseline.md (lines 15–16), if a security rule references a data store but the project contains no database resources, the rule is marked N/A and does not constitute a blocking finding. This distinction ensures that extensions remain relevant to the project context without creating unnecessary barriers.

Example: Security Baseline Enforcement

The following excerpt from security-baseline.opt-in.md demonstrates the opt-in prompt that activates blocking enforcement:

**Do you want to enable the Security Baseline extension?**  
A) Yes — enforce all SECURITY rules as blocking constraints (recommended)  
B) No — skip this extension

When the user selects option A, the engine loads the rule file and enforces every security requirement as a blocking constraint. During the Functional Design stage, if the generated artifacts lack encryption configurations for an RDS instance, the completion summary appears as follows:

## Construction – Functional Design (Unit: OrderService)

### Compliance Summary

| Rule | Status | Reason |
|------|--------|--------|
| SECURITY-01 | ❌ Non‑compliant | No encryption config on RDS |
| SECURITY-02 | ✅ Compliant | Access logs enabled on ALB |
| SECURITY-03 | N/A | No application component generated yet |

### Security Findings

- **SECURITY-01** – Encryption at Rest and in Transit is missing.

**Actions required**: Add an `encryption` block to the RDS resource definition.

[Request Changes]   (no "Continue to Next Stage" button)

The workflow cannot advance until the user resolves the encryption configuration and re-runs the stage, at which point the status changes to Compliant and the blocking condition lifts.

Summary

• Opt-in activation: Extensions load only after user confirmation via *.opt-in.md files, with status stored in aidlc-docs/aidlc-state.md.
• Blocking by default: All rule files declare that rules are blocking by default, making non-compliance a hard stop.
• UI enforcement: Non-compliant rules trigger the removal of the "Continue" button, leaving only "Request Changes" as an option.
• Audit trail: Every blocking finding is logged to aidlc-docs/audit.md with full context and rule identification.
• N/A exemption: Rules marked N/A due to inapplicable scope do not block progression.

Frequently Asked Questions

What happens if I disable an extension after previously enabling it?

Once disabled in aidlc-docs/aidlc-state.md, the AI-DLC runtime stops loading the corresponding rule file and ceases evaluation of its verification criteria. The workflow proceeds without checking those rules, effectively removing the blocking constraints for that extension. However, any previous blocking findings logged in aidlc-docs/audit.md remain as historical records.

Can individual rules within an extension be marked as non-blocking?

No. According to the source code in security-baseline.md and similar extension files, the declaration applies to the entire document: "All rules in this document are blocking by default." There is no per-rule override mechanism. If you need non-blocking recommendations, you must either disable the entire extension or modify the rule file directly, which deviates from the standard workflow.

How does the system handle temporary exemptions for rules that cannot be immediately satisfied?

The AI-DLC workflow does not support temporary exemptions or waivers for blocking rules. If a rule is non-compliant, the stage cannot complete until the underlying issue is resolved or the rule scope changes (triggering an N/A status). The only path forward is to address the finding and re-run the verification, or to disable the entire extension via the opt-in mechanism, which requires explicit user acknowledgment in the state file.

Where can I audit which specific rules blocked workflow progression?

Blocking findings are recorded in aidlc-docs/audit.md with timestamps, rule IDs (e.g., SECURITY-01), descriptions of the non-compliance, and the specific workflow stage where the block occurred. This file serves as the central compliance ledger for reviewing historical enforcement actions and resolution times.

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