Constraint System Specification

ACP Version: 1.0.0-revised Document Version: 1.0.0 Last Updated: 2024-12-17 Status: Revised Draft

Table of Contents

1. Overview
2. Lock Constraints
3. Style Constraints
4. Behavior Constraints
5. Quality Constraints
6. Constraint Violations
7. Constraint Merging
8. Examples

1. Overview

1.1 Purpose

Constraints define rules and guardrails for how AI systems should interact with code. They enable developers to:

• Protect critical code from unintended modifications
• Enforce coding standards and style guides
• Require specific behaviors during AI-assisted development
• Set quality gates for changes

Constraints are advisory to AI systems, meaning ACP cannot enforce them through access control or runtime checks.

1.2 Advisory Nature

Constraints are advisory. There is no mechanism to prevent an AI from violating constraints.

However, AI systems that claim ACP conformance (see main specification Section 10) MUST respect constraint semantics as specified in this document. The MUST/SHOULD language in constraint behavior tables applies to conformant AI systems.

Rationale: Advisory model enables:

• Flexibility for AI decision-making
• No runtime overhead
• Simple implementation
• Trust-based collaboration

AI systems MAY log constraint violations if tracking is enabled (Section 6).

1.3 Constraint Scope

Constraints can be applied at multiple levels:

See Inheritance & Cascade Specification for precedence rules.

1.4 Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2. Lock Constraints

Lock constraints control how freely AI can modify code.

2.1 Default Lock Level

Files and symbols without explicit @acp:lock annotation default to normal level.

This means:

• Absence of lock annotation permits unrestricted modification
• To restrict access, explicit annotation is required
• Default is permissive by design

2.2 Lock Levels

Lock Levels (most to least restrictive):

2.3 Lock Annotation Syntax

Basic Lock

@acp:lock <level>

With Reason

@acp:lock <level>
@acp:lock-reason <explanation>

2.4 Lock Level Details

frozen

Code MUST NOT be modified under any circumstances.

When to use:

• Generated code (will be overwritten)
• Vendor/third-party code
• Cryptographic constants
• Legal/compliance text
• Production configuration

AI Behavior:

• MUST NOT suggest any changes
• MUST NOT include in refactoring
• MAY explain code if asked
• MAY suggest alternatives elsewhere

Example:

/**
 * @acp:lock frozen
 * @acp:lock-reason "Production database credentials"
 */
const DB_CONFIG = { /* ... */ };

restricted

Limited modifications with explanation required. MUST get explicit user approval before any change.

When to use:

• Security-critical code
• Payment/financial processing
• Core business logic
• High-traffic hot paths

AI Behavior:

• MUST explain proposed changes before making them
• MUST get explicit user approval
• MUST use conservative approach
• SHOULD preserve existing patterns

Example:

/**
 * @acp:lock restricted
 * @acp:lock-reason "Security-critical authentication logic"
 */
export function validateToken(token: string): boolean {
  // Security-critical code
}

approval-required

Changes need explicit user approval, but may be proposed proactively.

When to use:

• Shared utilities used across teams
• Public API contracts
• Configuration defaults

AI Behavior:

• SHOULD get user approval for significant changes
• MAY make minor changes without approval
• MUST explain reasoning

tests-required

All changes MUST include corresponding tests.

When to use:

• Core business logic
• Public APIs
• Functions with complex logic

AI Behavior:

• MUST add/update tests with any modification
• SHOULD update existing tests if behavior changes
• MAY create new test file if none exists

docs-required

All changes MUST update documentation.

When to use:

• Public APIs
• User-facing features
• Configuration options

AI Behavior:

• MUST update documentation with changes
• SHOULD update inline comments
• MAY update external documentation

normal (default)

No special restrictions.

AI Behavior:

• MAY modify freely based on user request
• SHOULD still follow best practices
• SHOULD still maintain code quality

experimental

Encourage aggressive changes. Changes are expected to be reversible.

When to use:

• Prototypes
• Proofs-of-concept
• Experimental features

AI Behavior:

• MAY make aggressive optimizations
• MAY try novel approaches
• SHOULD track changes for reversal

3. Style Constraints

Style constraints guide code formatting and conventions.

3.1 Style Annotation Syntax

Named Style Guide

@acp:style <guide-name> - <directive>

With Custom Rules

@acp:style <guide-name> - <directive>
@acp:style-rules <rule1>, <rule2>, ... - <directive>

With Style Inheritance (RFC-0002)

@acp:style <custom-guide> - <directive>
@acp:style-extends <parent-guide> - <directive>

3.2 Built-in Style Guides

The following style guide names are reserved and recognized by default:

3.3 Custom Style Guides (RFC-0002)

Custom style guides can be defined in .acp.config.json:

{
  "documentation": {
    "styleGuides": {
      "company-react": {
        "extends": "airbnb-react",
        "description": "Company React conventions",
        "rules": ["prefer-function-components", "max-line-length=120"],
        "filePatterns": ["src/components/**/*.tsx"]
      }
    }
  }
}

See Config File Specification Section 9 for complete style guide configuration.

3.4 Style Inheritance (RFC-0002)

The @acp:style-extends annotation specifies a parent style guide:

/**
 * @acp:style company-standard - Follow our company coding standards
 * @acp:style-extends google-typescript - Based on Google TypeScript style
 * @acp:style-rules max-line-length=120 - Override specific rules
 */

Inheritance rules:

• Rules from parent guide apply first
• Child guide rules override parent rules
• Explicit @acp:style-rules override both

3.5 AI Behavior with Style

General Rules:

• MUST follow specified style guide for new code
• SHOULD NOT reformat existing code unless asked
• MUST maintain consistency with surrounding code
• SHOULD note style violations in existing code

Example:

/**
 * @acp:style google-typescript - Follow Google TypeScript style guide
 * @acp:style-rules max-line-length=100, no-any - Apply specific overrides
 */

4. Behavior Constraints

Behavior constraints modify how AI approaches code changes.

4.1 Behavior Annotation Syntax

@acp:behavior <approach>

4.2 Behavior Approaches

Example:

/**
 * @acp:behavior conservative
 */

5. Quality Constraints

Quality constraints specify additional checks needed.

5.1 Quality Annotation Syntax

@acp:quality <requirement1>, <requirement2>

5.2 Quality Requirements

Common Requirements:

• security-review: Requires security audit
• performance-test: Requires performance validation
• manual-test: Requires manual testing
• regression-test: Requires regression testing

Example:

/**
 * @acp:quality security-review, performance-test
 */

6. Constraint Violations

6.1 Violation Tracking (Optional)

Implementations MAY provide optional constraint violation logging.

Configuration (in .acp.config.json):

{
  "constraints": {
    "track_violations": true,
    "audit_file": ".acp.violations.log"
  }
}

Log Format (if enabled):

{
  "timestamp": "2024-12-17T15:30:00Z",
  "file": "src/auth/session.ts",
  "constraint": "lock:frozen",
  "action": "modify",
  "user_override": false,
  "context": "AI attempted modification of frozen file"
}

Implementations MAY provide --audit flag to enable tracking for a session.

Note: Violation tracking is OPTIONAL. Implementations claiming conformance are not required to provide this feature.

7. Constraint Merging

When constraints exist at multiple precedence levels, they merge according to these rules:

7.1 Lock Levels

Rule: Most restrictive wins

Example:

• Project default: normal
• Directory: approval-required
• File: restricted
• Result: restricted (most restrictive)

Precedence (most to least restrictive):

frozen > restricted > approval-required > tests-required > docs-required > normal > experimental

7.2 Style Guides

Rule: Most specific guide wins, but rules from all levels accumulate

Example:

• Project: google-typescript
• Directory: custom rule max-line-length=100
• File: custom rule indent=2
• Result:
  • Base guide: google-typescript (from project)
  • Additional rules: max-line-length=100, indent=2 (accumulated)

7.3 Behavior Constraints

Rule: Most specific wins completely (no merging)

Example:

• Project: conservative
• File: aggressive
• Result: aggressive (file-level overrides)

7.4 Quality Requirements

Rule: Requirements accumulate (all levels apply)

Example:

• Project: tests-required
• File: security-review
• Result: Both requirements apply

See Inheritance & Cascade Specification for complete merging details.

8. Examples

8.1 Security-Critical File

/**
 * @acp:module "Authentication Core"
 * @acp:domain authentication, security
 * @acp:lock restricted
 * @acp:lock-reason "Security-critical code. All changes require security review."
 * @acp:behavior conservative
 * @acp:quality security-review, tests-required
 */
 
export class AuthenticationService {
  /**
   * @acp:lock frozen
   * @acp:lock-reason "Cryptographic constant - never modify"
   */
  private static readonly HASH_ROUNDS = 12;
 
  /**
   * @acp:summary "Validates user credentials"
   */
  async validateCredentials(email: string, password: string): Promise<User | null> {
    // Implementation
  }
}

8.2 Generated Code

/**
 * @acp:lock frozen
 * @acp:lock-reason "Auto-generated from schema.prisma. Edit schema instead."
 *
 * DO NOT EDIT - This file is generated by Prisma
 */
 
export interface User {
  id: string;
  email: string;
  // ...
}

8.3 Public API

/**
 * @acp:module "Public API v2"
 * @acp:domain api
 * @acp:stability stable
 * @acp:lock approval-required
 * @acp:lock-reason "Public API - breaking changes affect customers"
 * @acp:quality documented
 */
 
export interface ApiResponse<T> {
  // Public API contract
}

Appendix A: Quick Reference

Merging Rules:

• Lock levels: Most restrictive wins
• Style guides: Most specific guide + accumulated rules
• Style extends: Parent rules first, child overrides
• Behavior: Most specific wins
• Quality: All requirements accumulate

Appendix B: Related Documents

• Annotation Syntax - Annotation syntax definition
• Cache Format - How constraints are indexed
• Debug Sessions - Debug and hack tracking
• Inheritance & Cascade - Constraint inheritance rules
• Configuration - Constraint configuration

End of Constraint System Specification