Bootstrap & AI Integration Specification

This project uses ACP. @acp:* comments in code are directives for you.
BEFORE editing: acp constraints <path>
Explore: acp query symbol|file|domain <name>
Map: acp map <path>
Help: acp knowledge "question"

This project uses ACP (AI Context Protocol). @acp:* comments in code are
directives that MUST be followed.
 
WORKFLOW:
1. BEFORE modifying any file, run: acp constraints <path>
2. Respect lock levels: frozen (never modify), restricted (approval required)
3. Read the directive text after " - " in each annotation
 
COMMANDS:
- acp constraints <path>  - Check file constraints before editing
- acp query file <path>   - Get file context with symbols and constraints
- acp query symbol <name> - Get symbol details with callers/callees
- acp query domain <name> - Get domain files and relationships
- acp map <path>          - Get visual file map with constraints
- acp knowledge "q"       - Ask about the codebase
 
CONSTRAINT LEVELS:
- frozen: MUST NOT modify under any circumstances
- restricted: MUST explain changes and wait for approval
- approval-required: SHOULD request approval for significant changes
- tests-required: MUST add tests when modifying
- normal: May modify following best practices
- experimental: May modify aggressively
 
INLINE MARKERS:
- @acp:critical: Extra caution required
- @acp:todo: Pending work
- @acp:fixme: Known issue
- @acp:hack: Temporary solution

┌─────────────────────┐
│ User requests edit  │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ acp constraints     │
│ <target-file>       │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Check lock level    │
└─────────┬───────────┘
          │
    ┌─────┴─────┐
    │           │
    ▼           ▼
┌───────┐   ┌───────────┐
│frozen │   │ other     │
│       │   │           │
│REFUSE │   │ PROCEED   │
│ EDIT  │   │ w/context │
└───────┘   └───────────┘

// @acp:lock frozen - MUST NOT modify this file under any circumstances

acp constraints <path>

src/auth/session.ts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Level: restricted
Directive: Explain proposed changes and wait for explicit approval before modifying
 
Reason: Security-critical authentication code
 
Annotations:
  @acp:lock restricted
    → Explain proposed changes and wait for explicit approval
  @acp:ref https://docs.example.com/auth
    → Consult before making changes to this code

acp map <path>

src/auth/session.ts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Purpose: User authentication and session management
Domain: authentication
Owner: auth-team
Lines: 234
Lock: restricted
 
Symbols:
  ┌ SessionService (class) [L:15-89]
  │ └ validateSession (method) [L:20-45] 🔒 frozen
  │ └ refreshSession (method) [L:50-75]
  └ createSession (function) [L:100-120]
 
Inline:
  L:45  @acp:critical → Review with extreme care
  L:78  @acp:todo → Add rate limiting

acp query file <path>

{
  "path": "src/auth/session.ts",
  "purpose": "User authentication and session management",
  "module": "Session Service",
  "domain": "authentication",
  "owner": "auth-team",
  "lines": 234,
  "language": "typescript",
  "constraints": {
    "lock_level": "restricted",
    "lock_reason": "Security-critical authentication code",
    "directive": "Explain proposed changes and wait for explicit approval"
  },
  "symbols": [
    {
      "name": "validateSession",
      "type": "method",
      "lines": [20, 45],
      "purpose": "Validates JWT token and returns session data",
      "constraints": {
        "lock_level": "frozen",
        "directive": "MUST NOT modify this function"
      }
    }
  ],
  "inline": [
    {
      "type": "critical",
      "line": 45,
      "directive": "Review with extreme care"
    }
  ]
}

acp query symbol <qualified-name>

{
  "name": "validateSession",
  "qualified_name": "src/auth/session.ts:SessionService.validateSession",
  "type": "method",
  "file": "src/auth/session.ts",
  "lines": [20, 45],
  "purpose": "Validates JWT token and returns session data",
  "signature": "(token: string) => Promise<Session | null>",
  "params": [
    {
      "name": "token",
      "description": "JWT token string",
      "directive": "Ensure token is valid JWT before calling"
    }
  ],
  "returns": {
    "description": "Session object or null if invalid",
    "directive": "Handle null case appropriately"
  },
  "constraints": {
    "lock_level": "frozen",
    "directive": "MUST NOT modify this function"
  },
  "callers": [
    "src/api/middleware.ts:authMiddleware [L:34]"
  ],
  "callees": [
    "src/auth/jwt.ts:verifyToken [L:15]"
  ]
}

src/auth/session.ts:SessionService.validateSession
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Location: src/auth/session.ts:20-45
Type: method
Purpose: Validates JWT token and returns session data
 
Signature:
  (token: string) => Promise<Session | null>
 
Parameters:
  token: JWT token string
    → Ensure token is valid JWT before calling
 
Returns:
  Session object or null if invalid
    → Handle null case appropriately
 
Constraints:
  Lock: frozen
    → MUST NOT modify this function
 
Callers:
  • src/api/middleware.ts:authMiddleware [L:34]
 
Callees:
  • src/auth/jwt.ts:verifyToken [L:15]

acp query symbol <name> --json

validateSession [src/auth/session.ts:20-45] 🔒frozen
Purpose: Validates JWT token and returns session data
Directive: MUST NOT modify this function

## ACP Integration
 
This project uses ACP. Before modifying any file:
1. Run `acp constraints <path>`
2. Follow the directive in any `@acp:*` annotations
3. Respect lock levels (frozen = never modify)

# ACP Protocol
This codebase uses @acp:* annotations as directives.
Before editing, check: acp constraints <path>
Follow directives after " - " in annotations.
Lock levels: frozen (never), restricted (approval), normal (ok)

# ACP Protocol
 
Check `@acp:*` comments for constraints before suggesting edits.
- `@acp:lock frozen` = Do not modify
- `@acp:lock restricted` = Request approval first
- Directives after " - " are instructions to follow