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 (for constraint reviews), safety-checks (for enforcement)
## Failure Modes
| Condition | Behavior |
|-----------|----------|
| Invalid sub-command | List available sub-commands |
| Constraint not found | Error with suggestion to search |
| Ineligible observation | Show missing criteria, suggest /fm status |
| Circuit OPEN | Block action, show recovery guidance |
| Override without reason | Require reason for audit trail |
## Next Steps
After invoking this skill:
| Condition | Action |
|-----------|--------|
| Constraint generated | Add to `output/constraints/draft/`, notify user |
| Constraint activated | Move to `output/constraints/active/` |
| Action blocked | Log to `output/hooks/blocked.log`, explain why |
| Circuit OPEN | Surface to user with recovery guidance |
| Override used | Audit log entry, temporary bypass only |
## Workspace Files
This skill reads/writes:
```
output/
├── constraints/
│ ├── draft/ # Pending constraints
│ │ └── CON-YYYYMMDD-XXX.md
│ ├── active/ # Enforced constraints
│ │ └── CON-YYYYMMDD-XXX.md
│ ├── retired/ # Historical constraints
│ │ └── CON-YYYYMMDD-XXX.md
│ └── metadata.json # VFM scoring data
└── hooks/
└── blocked.log # Actions blocked by constraints
```
## Security Considerations
**What this skill accesses:**
- Configuration files in `.openclaw/constraint-engine.yaml` and `.claude/constraint-engine.yaml`
- Observation data from failure-memory (via `.learnings/` directory)
- Its own output directories `output/constraints/` and `output/hooks/`
**What this skill does NOT access:**
- Files outside declared workspace paths
- System environment variables
- Network resources or external APIs
**What this skill does NOT do:**
- Send data to external services
- Execute arbitrary code
- Modify files outside its workspace
**Dependency note:**
This skill reads observation data from `failure-memory` skill's workspace (`.learnings/`).
Install `leegitw/failure-memory` for full constraint generation functionality.
Without failure-memory, constraint generation will have no observation data to process.
**Audit logging:**
Override actions are logged to `output/hooks/blocked.log` for audit purposes.
Logs are stored locally in the workspace only.
## Acceptance Criteria
- [ ] `/ce check` validates action against active constraints
- [ ] `/ce check` blocks when constraint violated, shows reason
- [ ] `/ce generate` creates constraint from eligible observation
- [ ] `/ce generate` applies positive reframing
- [ ] `/ce status` shows circuit breaker state and active constraints
- [ ] `/ce override` creates temporary bypass with audit log
- [ ] `/ce lifecycle` transitions constraint through states
- [ ] `/ce version` increments constraint version preserving history
- [ ] Circuit breaker trips at severity-appropriate thresholds
- [ ] Workspace files follow documented structure
---
*Consolidated from 7 skills as part of agentic skills consolidation (2026-02-15).*
标签
skill
ai
