# System Gates

> Blocking checkpoints that MUST pass before proceeding.
> Gates enforce hard rules that cannot be bypassed.

---

## Gate Philosophy

Gates are **BLOCKING**. If a gate fails:
1. Claude MUST stop
2. Claude MUST report the failure
3. Claude MUST NOT proceed until resolved
4. User CANNOT override blocking gates (only fix the issue)

---

## Gate Definitions

### `analyze_gate`

**Phase:** Before ANALYZE → PLAN transition
**Purpose:** Ensure adequate analysis was performed

```
GATE: analyze_gate
├── REQUIRES:
│   ✓ Read relevant source files
│   ✓ Understood existing code patterns
│   ✓ Identified affected files
│   ✓ Checked BLUEPRINT.md for requirements
│   ✓ Checked AI_RULES.md for standards
│
├── ON_PASS:
│   └── Proceed to: PLAN phase
│
└── ON_FAIL:
    └── BLOCK: "Insufficient analysis"
    └── Report: what's missing
    └── Return to: ANALYZE phase
```

---

### `plan_approval_gate`

**Phase:** Before PLAN → IMPLEMENT transition
**Purpose:** User must approve the plan before implementation

```
GATE: plan_approval_gate
├── REQUIRES:
│   ✓ Plan has been presented to user
│   ✓ Suggestions (if applicable) have been shown
│   ✓ User has explicitly approved
│       - "yes", "proceed", "go ahead", "approved", etc.
│       - OR selected which suggestions to include
│
├── ON_PASS:
│   └── Record: approved suggestions
│   └── Proceed to: IMPLEMENT phase
│
├── ON_FAIL (no approval):
│   └── BLOCK: "Awaiting user approval"
│   └── State: "Should I proceed with this plan?"
│   └── Wait for: user response
│
└── ON_REJECT (user says no):
    └── Ask: "What should I change?"
    └── Return to: PLAN phase
    └── Revise: based on feedback
```

**Approval Detection:**
```
APPROVED if user says:
- "yes" / "y" / "yeah" / "yep"
- "proceed" / "go ahead" / "do it"
- "approved" / "lgtm" / "looks good"
- "all" / "include all" (for suggestions)
- "required" / "required only"
- Specific numbers: "1, 3, 5" (for suggestions)

NOT APPROVED if user says:
- "no" / "n" / "nope"
- "wait" / "hold on"
- "change" / "modify"
- Question asking for clarification
```

---

### `verify_gate`

**Phase:** After IMPLEMENT, before AUDIT/COMMIT
**Purpose:** Code must pass TypeScript and ESLint checks

```
GATE: verify_gate
├── REQUIRES:
│   ✓ npm run typecheck → exit code 0
│   ✓ npm run lint → exit code 0 (0 warnings)
│   ✓ No TypeScript errors in any file
│   ✓ No ESLint errors or warnings
│
├── COMMANDS:
│   npm run verify
│   (which runs: npm run typecheck && npm run lint)
│
├── ON_PASS:
│   └── Report: "✅ Verification passed"
│   └── Proceed to: AUDIT phase (if feature) or COMMIT gate
│
└── ON_FAIL:
    └── BLOCK: "⛔ Verification failed"
    └── Report: all errors with file:line
    └── Enter: fix_loop (from system/loops.md)
    └── After fix: re-check gate
```

**Output Format:**
```
## Verify Gate Check

| Check | Status | Details |
|-------|--------|---------|
| TypeScript | ✅/⛔ | X errors found |
| ESLint | ✅/⛔ | X warnings found |

Gate Status: ✅ PASSED / ⛔ BLOCKED
```

---

### `audit_gate`

**Phase:** After VERIFY, before COMMIT (for features)
**Purpose:** No orphan features, no circular dependencies

```
GATE: audit_gate
├── REQUIRES:
│   ✓ npm run audit:ui → no orphan features
│   ✓ npm run audit:cycles → no circular dependencies
│
├── CHECKS:
│   1. UI Enforcement:
│      - Every API endpoint has a UI that calls it
│      - Every hook is used by a component
│      - Every utility is imported somewhere
│      - User can access every feature
│
│   2. Circular Dependencies:
│      - No A → B → A import cycles
│      - No longer chains (A → B → C → A)
│
├── ON_PASS:
│   └── Report: "✅ All audits passed"
│   └── Proceed to: pre_commit_gate
│
├── ON_UI_FAIL:
│   └── BLOCK: "⛔ Orphan feature detected"
│   └── Report: features missing UI
│   └── Enter: ui_fix_loop
│   └── After fix: re-check gate
│
└── ON_CYCLE_FAIL:
    └── BLOCK: "⛔ Circular dependency detected"
    └── Report: cycle paths
    └── Enter: cycle_fix_loop
    └── After fix: re-check gate
```

---

### `pre_commit_gate`

**Phase:** Before COMMIT
**Purpose:** Final check before committing - ALL rules enforced

```
GATE: pre_commit_gate
├── REQUIRES:
│   ✓ verify_gate passed (TypeScript + ESLint clean)
│   ✓ audit_gate passed (no orphans, no cycles)
│   ✓ No TODO comments in changed files
│   ✓ No FIXME comments in changed files
│   ✓ No console.log in changed files
│   ✓ No console.debug in changed files
│   ✓ No console.info in changed files
│   ✓ Commit message follows conventional format
│
├── CHECKS:
│   1. Re-verify: npm run verify
│   2. Check diff: grep -E "TODO|FIXME"
│   3. Check diff: grep "console\.(log|debug|info)"
│   4. Validate: commit message format
│
├── COMMIT_MESSAGE_FORMAT:
│   type(scope): description
│
│   Valid types: feat, fix, docs, style, refactor,
│                perf, test, build, ci, chore, revert
│
│   Examples:
│   - feat(auth): add login page
│   - fix(api): handle null response
│   - refactor(utils): extract date helpers
│
├── ON_PASS:
│   └── Report: "✅ All pre-commit checks passed"
│   └── Show: commit preview (files + message)
│   └── Ask: "Should I commit?"
│   └── Wait for: user confirmation
│
└── ON_FAIL:
    └── BLOCK: "⛔ Cannot commit"
    └── Report: ALL blocking issues
    └── Route to: appropriate fix action
    └── After fix: re-check gate
```

**Output Format:**
```
## Pre-Commit Gate Check

| Check | Status | Details |
|-------|--------|---------|
| TypeScript | ✅ | No errors |
| ESLint | ✅ | No warnings |
| UI Enforcement | ✅ | All features have UI |
| Circular Deps | ✅ | No cycles |
| TODO/FIXME | ✅ | None in diff |
| console.log | ✅ | None in diff |
| Commit Message | ✅ | Valid format |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ ALL GATES PASSED

Ready to commit:
- 3 files changed
- Message: "feat(auth): add login page"

Should I proceed with this commit?
```

---

### `destructive_action_gate`

**Phase:** Before any destructive action
**Purpose:** User must confirm dangerous operations

```
GATE: destructive_action_gate
├── TRIGGERS_ON:
│   - Deleting files
│   - Removing significant code (>50 lines)
│   - Changing database schema
│   - Modifying authentication logic
│   - Changing API contracts
│   - Force operations (git push --force, etc.)
│
├── REQUIRES:
│   ✓ User explicitly confirms the action
│   ✓ Impact has been clearly explained
│
├── FORMAT:
│   ⚠️ **Warning:** This will [describe impact].
│
│   Files affected:
│   - [file1]
│   - [file2]
│
│   This action [is/is not] reversible.
│
│   **Should I proceed?**
│
└── ON_CONFIRM:
    └── Proceed with: action
    └── On reject: cancel action
```

---

## Gate Hierarchy

Gates are checked in order. Later gates assume earlier gates passed.

```
1. analyze_gate
      │
      ▼
2. plan_approval_gate
      │
      ▼
3. [IMPLEMENT]
      │
      ▼
4. verify_gate
      │
      ▼
5. audit_gate (if feature/component)
      │
      ▼
6. pre_commit_gate
      │
      ▼
7. [COMMIT]
```

---

## Gate Override Policy

**CANNOT be overridden by user:**
- `verify_gate` - TypeScript/ESLint errors
- `audit_gate` - Orphan features
- `pre_commit_gate` - Blocking rule violations

**CAN be acknowledged by user:**
- `destructive_action_gate` - With explicit "yes, delete it"

**User controls:**
- `plan_approval_gate` - User decides when to proceed

---

## Reporting Gate Status

Claude MUST show gate status at phase transitions:

```
## Gate: pre_commit_gate

Checking requirements...

[1/7] TypeScript errors: ✅ PASS (0 errors)
[2/7] ESLint warnings: ✅ PASS (0 warnings)
[3/7] UI Enforcement: ✅ PASS (no orphans)
[4/7] Circular deps: ✅ PASS (no cycles)
[5/7] TODO/FIXME: ✅ PASS (none found)
[6/7] console.log: ✅ PASS (none found)
[7/7] Commit format: ✅ PASS (valid)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ GATE PASSED - Ready to proceed
```

Or on failure:

```
## Gate: pre_commit_gate

Checking requirements...

[1/7] TypeScript errors: ✅ PASS
[2/7] ESLint warnings: ✅ PASS
[3/7] UI Enforcement: ⛔ FAIL
      └── Missing UI for: /api/users endpoint
[4/7] Circular deps: ✅ PASS
[5/7] TODO/FIXME: ⛔ FAIL
      └── Found: src/utils.ts:42 "TODO: implement"
[6/7] console.log: ✅ PASS
[7/7] Commit format: ✅ PASS

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⛔ GATE BLOCKED - Cannot proceed

Issues to resolve:
1. Add UI component for /api/users
2. Remove TODO comment at src/utils.ts:42

Fixing now...
```

---

## Quick Reference

| Gate | When | Blocking Rule |
|------|------|---------------|
| `analyze_gate` | Before planning | Must read relevant files |
| `plan_approval_gate` | Before implementing | User must approve |
| `verify_gate` | After implementing | Zero TS/ESLint errors |
| `audit_gate` | Before committing features | No orphans, no cycles |
| `pre_commit_gate` | Before any commit | All rules enforced |
| `destructive_action_gate` | Before dangerous ops | User must confirm |

**Gates are non-negotiable. Fix issues, don't bypass gates.**