constraint-engine

从结果中学习，而不是从指令中学习——从经验中产生并实施约束

# constraint-engine (制約)

Unified skill for constraint generation, pre-action checking, circuit breaker management,
and constraint lifecycle. Consolidates 7 granular skills into a single enforcement system.

**Trigger**: 行動前∨閾値到達 (pre-action or threshold reached)

**Source skills**: constraint-generator, circuit-breaker, emergency-override, constraint-lifecycle, constraint-versioning, positive-framer (partial), contextual-injection (partial)

## Installation

```bash
openclaw install leegitw/constraint-engine
```

**Dependencies**: `leegitw/failure-memory` (for eligibility data)

```bash
# Install with dependencies
openclaw install leegitw/context-verifier
openclaw install leegitw/failure-memory
openclaw install leegitw/constraint-engine
```

**Standalone usage**: Requires failure-memory for constraint generation from observations.
For full lifecycle management, install the complete suite (see [Neon Agentic Suite](../README.md)).

**Data handling**: This skill operates within your agent's trust boundary. When triggered,
it uses your agent's configured model for constraint checking and generation. No external APIs
or third-party services are called. Results are written to `output/constraints/` in your workspace.

## What This Solves

Instructions get ignored. Rules get forgotten. Documentation goes unread. This skill takes a different approach — constraints generated from actual failures:

1. **Generate constraints** from observations that meet the eligibility threshold (`R≥3 ∧ C≥2`)
2. **Enforce constraints** at runtime with a circuit breaker (CLOSED → OPEN → HALF-OPEN)
3. **Manage lifecycle** from proposal through adoption to retirement

**The insight**: A constraint born from "this actually broke" carries more weight than "this might break." Consequences teach better than instructions.

## Usage

```
/ce <sub-command> [arguments]
```

## Sub-Commands

| Command | CJK | Logic | Trigger |
|---------|-----|-------|---------|
| `/ce check` | 検査 | action→constraints[]→pass∨block | Next Steps (auto) |
| `/ce generate` | 生成 | eligible(obs)→constraint | Next Steps (auto) |
| `/ce status` | 状態 | active[], circuit∈{CLOSED,OPEN,HALF} | Explicit |
| `/ce override` | 上書 | constraint→bypass(temp), audit.log++ | Explicit |
| `/ce lifecycle` | 周期 | state∈{draft→active→retiring→retired} | Explicit |
| `/ce version` | 版本 | constraint→v++, history.preserve | Explicit |
| `/ce threshold` | 閾値 | user∨context→custom_threshold | Explicit |

## Arguments

### /ce check

| Argument | Required | Description |
|----------|----------|-------------|
| action | Yes | Action to check against constraints |
| --severity | No | Minimum severity to check: `critical`, `important`, `minor` (default: all) |

### /ce generate

| Argument | Required | Description |
|----------|----------|-------------|
| observation | Yes | Observation ID or pattern to generate constraint from |
| --force | No | Generate even if eligibility criteria not met |

### /ce status

| Argument | Required | Description |
|----------|----------|-------------|
| --circuit | No | Show circuit breaker status only |
| --active | No | Show active constraints only |

### /ce override

| Argument | Required | Description |
|----------|----------|-------------|
| constraint | Yes | Constraint ID to override |
| reason | Yes | Reason for override (logged for audit) |
| --duration | No | Override duration (default: "session") |

### /ce lifecycle

| Argument | Required | Description |
|----------|----------|-------------|
| constraint | Yes | Constraint ID |
| state | Yes | Target state: `draft`, `active`, `retiring`, `retired` |

### /ce version

| Argument | Required | Description |
|----------|----------|-------------|
| constraint | Yes | Constraint ID |
| --bump | No | Version bump type: `major`, `minor`, `patch` (default: minor) |

### /ce threshold

| Argument | Required | Description |
|----------|----------|-------------|
| --R | No | Custom recurrence threshold (default: 3) |
| --C | No | Custom confirmation threshold (default: 2) |
| --reset | No | Reset to default thresholds |

## Configuration

Configuration is loaded from (in order of precedence):
1. `.openclaw/constraint-engine.yaml` (OpenClaw standard)
2. `.claude/constraint-engine.yaml` (Claude Code compatibility)
3. Defaults (built-in)

```yaml
# .openclaw/constraint-engine.yaml
thresholds:
  R: 3                       # Recurrence threshold (default: 3)
  C: 2                       # Confirmation threshold (default: 2)
  false_positive_max: 0.2    # Max D/(C+D) ratio (default: 0.2)
circuit_breaker:
  critical_threshold: 3      # Violations to trip for CRITICAL
  important_threshold: 5     # Violations to trip for IMPORTANT
  minor_threshold: 10        # Violations to trip for MINOR
  window_days: 30            # Violation window (default: 30 days)
lifecycle:
  review_reminder_days: 80   # Days before 90-day review to remind
```

## Core Logic

### Eligibility Criteria

Observation becomes eligible for constraint when:

```
R≥3 ∧ C≥2 ∧ D/(C+D)<0.2 ∧ sources≥2
```

| Criterion | Meaning |
|-----------|---------|
| R≥3 | At least 3 recurrences |
| C≥2 | At least 2 human confirmations |
| D/(C+D)<0.2 | False positive rate under 20% |
| sources≥2 | Observed by at least 2 different sources |

### Positive Reframing

Constraints are automatically reframed positively:

| Negative | Positive |
|----------|----------|
| "Don't commit without tests" | "Always run tests before commit" |
| "Don't push to main directly" | "Always create PR for main changes" |
| "Don't deploy without review" | "Always get code review before deployment" |
| "Don't skip migrations" | "Always run database migrations before release" |

### Example: Code Review Constraint

```
[CHECK BLOCKED] deploy production
Constraint violated: CON-20260212-005
  "Always get code review approval before production deployment"
  Severity: CRITICAL

Action: Request review via /ro twin, then retry deployment.
```

### Example: Deployment Gate Constraint

```
[CHECK PASSED] deploy staging
Active constraints checked: 3
  ✓ CON-20260210-001: Tests pass
  ✓ CON-20260211-002: Staging smoke test
  ✓ CON-20260212-003: Database migration verified
All constraints satisfied. Proceeding to staging.
```

### Circuit Breaker States

| State | Meaning | Behavior |
|-------|---------|----------|
| CLOSED | Normal operation | Constraints enforced |
| OPEN | Circuit tripped | Block all related actions |
| HALF-OPEN | Testing recovery | Allow limited actions |

### Circuit Breaker Thresholds

| Severity | Threshold | Window |
|----------|-----------|--------|
| CRITICAL | 3 violations | 30 days |
| IMPORTANT | 5 violations | 30 days |
| MINOR | 10 violations | 30 days |

### Constraint Lifecycle

```
draft → active → retiring → retired
  │        │         │
  └────────┴─────────┴── 90-day review gates
```

## Output

### /ce check output (pass)

```
[CHECK PASSED] git commit -m "feature"
Active constraints checked: 5
All constraints satisfied.
```

### /ce check output (block)

```
[CHECK BLOCKED] git commit -m "feature"

Constraint violated: CON-20260210-001
  "Always run tests before commit"
  Severity: CRITICAL

Action: Run tests first, then retry commit.
Override: /ce override CON-20260210-001 "emergency hotfix"
```

### /ce status output

```
=== Constraint Engine Status ===

Circuit Breaker: CLOSED (healthy)

Active Constraints (5):
- CON-20260210-001: Always run tests before commit [CRITICAL]
- CON-20260212-003: Always lint before commit [IMPORTANT]
- ...

Draft Constraints (2):
- CON-20260215-001: Pending approval

Violations (30d): 2
```

### /ce generate output

```
[CONSTRAINT GENERATED]

From: OBS-20260210-003 (lint-before-commit)
ID: CON-20260215-001
Text: "Always run lint before commit"
Severity: IMPORTANT
Status: draft

Next: Review and approve with /ce lifecycle CON-20260215-001 active
```

## Integration

- **Layer**: Core
- **Depends on**: failure-memory (for eligibility data)
- **Used by**: governance (f