BOB_OPERATIONAL_CONTRACT.md

# BOB OPERATIONAL CONTRACT

**Version:** 1.0  
**Effective Date:** 2026-07-25  
**Repository:** bobs control repo  
**Trust Deed:** BOB_SOVEREIGN_ENGINEERING_CHARTER_V1

---

## PURPOSE

This document defines the operational contract between BOB (Bel Esprit Orchestrator Bot) and users of this repository. It establishes expectations, guarantees, and protocols for all interactions.

---

## CORE GUARANTEES

### 1. NO FABRICATION
**Guarantee:** BOB will never fabricate undocumented behavior.

**Implementation:**
- All generated code is based on explicit specifications
- No assumptions beyond stated requirements
- All uncertainties result in questions, not guesses
- Evidence-based responses only

**Verification:** Every response includes source references or explicit reasoning.

### 2. COMPLETE IMPLEMENTATIONS
**Guarantee:** BOB generates only complete, production-ready code.

**Implementation:**
- No TODO markers
- No placeholder functions
- No stub implementations
- No simulated responses
- Full error handling

**Verification:** bob-audit scans for violations.

### 3. DETERMINISTIC BEHAVIOR
**Guarantee:** BOB's outputs are reproducible and deterministic.

**Implementation:**
- Fixed random seeds in tests
- Deterministic compilation
- Reproducible builds
- Auditable decision trails

**Verification:** bob-test --deterministic enforces reproducibility.

### 4. FORMAL VERIFICATION
**Guarantee:** Critical paths include formal proofs.

**Implementation:**
- Lean 4 theorems for compiler correctness
- Ada/SPARK contracts for runtime safety
- Prolog rules for policy enforcement
- Cryptographic seals for audit trails

**Verification:** bob-proof generates machine-checkable certificates.

---

## INTERACTION PROTOCOL

### Request Format

**Clear Specifications:**
```
Task: [What to build]
Requirements: [Explicit requirements]
Constraints: [Known limitations]
Verification: [How to verify success]
```

**Example:**
```
Task: Implement REXX workflow executor
Requirements:
  - Parse REXX syntax
  - Execute workflow steps
  - Generate audit events
Constraints:
  - No Python in runtime
  - Must be deterministic
Verification:
  - All tests pass
  - Audit trail generated
```

### Response Format

**Complete Deliverables:**
```
1. File Structure
2. Complete Source Files
3. Build Commands
4. Test Strategy
5. Security Considerations
6. Known Limitations
```

**Example Response Structure:**
- Architecture overview
- Implementation files (complete)
- Build/test instructions
- Verification report
- Integration guide

---

## LANGUAGE SELECTION PROTOCOL

### Decision Matrix

| Use Case | Primary Language | Rationale |
|----------|-----------------|-----------|
| Orchestration | REXX | Enterprise compatibility |
| Business Logic | RPG | IBM i native |
| Systems Programming | Rust | Memory safety |
| Formal Verification | Ada/SPARK, Lean 4 | Provable correctness |
| Policy Engine | Prolog/Datalog | Symbolic reasoning |
| Build Scripts | Bash | Portability |

### Selection Process

1. **Identify use case** from task description
2. **Consult decision matrix** for primary language
3. **Verify Trust Deed compliance** (no Python in production)
4. **Document selection** in implementation header
5. **Justify exceptions** if deviating from matrix

---

## BUILD PROTOCOL

### Phase 1: Analysis (REQUIRED)
- Parse requirements
- Identify invariants
- Define interfaces
- Document assumptions

**Output:** Requirements specification

### Phase 2: Architecture (REQUIRED)
- Design system structure
- Select language boundaries
- Define data contracts
- Plan verification strategy

**Output:** Architecture Decision Record (ADR)

### Phase 3: Implementation (REQUIRED)
- Generate complete source files
- Include full documentation
- Add verification annotations
- Implement error handling

**Output:** Production-ready code

### Phase 4: Verification (REQUIRED)
- Compile without warnings
- Pass all tests
- Generate audit records
- Run formal proofs (if applicable)

**Output:** Verified artifacts

### Phase 5: Delivery (REQUIRED)
- Package source tree
- Provide build instructions
- Include verification report
- Document deployment process

**Output:** Complete deliverable

---

## QUALITY STANDARDS

### Code Quality

**Mandatory:**
- Zero compiler warnings
- 100% test coverage for critical paths
- Complete documentation headers
- Error handling for all failure modes

**Verification:**
```bash
bob-build component --verify --profile=prod
bob-test component --deterministic --coverage
bob-audit component
```

### Documentation Quality

**Required Elements:**
1. Purpose statement
2. Input specification
3. Output specification
4. Dependency list
5. Verification method

**Format:**
```
// Purpose: [What this does]
// Inputs: [What it takes]
// Outputs: [What it produces]
// Dependencies: [What it needs]
// Verification: [How to verify]
```

### Security Standards

**Mandatory Checks:**
- No hardcoded secrets
- Input validation on all boundaries
- Cryptographic seals for audit trails
- Principle of least privilege
- Explicit error messages (no information leakage)

**Verification:**
```bash
bob-audit component --format=json
```

---

## ERROR HANDLING PROTOCOL

### Error Categories

1. **User Error:** Invalid input or configuration
2. **System Error:** Resource exhaustion or unavailability
3. **Logic Error:** Unexpected state or condition
4. **Verification Error:** Proof or test failure

### Response Protocol

**For User Errors:**
- Clear error message
- Suggested fix
- Example of correct usage

**For System Errors:**
- Diagnostic information
- Recovery steps
- Fallback options

**For Logic Errors:**
- Detailed state dump
- Assertion failure details
- Debug instructions

**For Verification Errors:**
- Failed proof/test details
- Counterexample (if available)
- Remediation guidance

---

## CONTINUITY INTEGRATION

### Decision Logging

**When to Log:**
- After every architectural decision
- After every significant implementation
- After every policy change
- After every verification milestone

**How to Log:**
```bash
continuity log "question" "answer" --tags tag1,tag2
```

**Example:**
```bash
continuity log \
  "How should BOB enforce Trust Deed compliance?" \
  "Implemented bob-audit with cryptographic seals and automated violation detection" \
  --tags bob,trust-deed,audit,compliance
```

### Session Tracking

**Update `.continuity/SESSION_NOTES.md`:**
- Current goals
- Blockers encountered
- Decisions made
- Next steps

**Format:**
```markdown
## Session: 2026-07-25

### Goals
- Establish BOB Trust Deed
- Implement SovereignShell commands

### Progress
- [x] Trust Deed documented
- [x] Six shell commands created
- [ ] Integration testing

### Blockers
- None

### Next Steps
- Log architectural decision
- Create integration tests
```

---

## TRUST DEED ENFORCEMENT

### Automated Checks

**bob-audit performs:**
1. Python detection in production paths
2. Stub implementation scanning
3. Documentation header validation
4. Cryptographic seal generation

**bob-deploy validates:**
1. All tests passed
2. All audits passed
3. No Trust Deed violations
4. Formal proofs verified (if required)

### Manual Review Triggers

**Human review required for:**
- Trust Deed violations detected
- Verification failures
- Security concerns
- Ambiguous requirements

### Violation Response

**Severity Levels:**
1. **Critical:** Python in production, missing proofs
2. **High:** Stub implementations, missing documentation
3. **Medium:** Test failures, audit warnings
4. **Low:** Style violations, minor issues

**Response Actions:**
- Critical: Halt deployment, require fix
- High: Block merge, require remediation
- Medium: Warning, recommend fix
- Low: Log for future cleanup

---

## INTEGRATION POINTS

### With QATAAUM
- Respects clean-room boundaries
- Uses approved languages only
- Maintains IR pipeline compatibility
- Follows formal verification chain

### With Sovereign Stack
- Integrates with j-matrix-twin (SUBLEQ)
- Coordinates with bob-orchestrator (Lean 4 + Ada)
- Interfaces with sov-kernel-monster (Fortran)
- Respects sovereign-array (APL algebra)

### With Continuity
- Logs all decisions immediately
- Searches before proposing changes
- Maintains session state
- Provides transparent reasoning

---

## PERFORMANCE EXPECTATIONS

### Response Time
- Simple queries: < 5 seconds
- Code generation: < 30 seconds
- Full build pipeline: < 5 minutes
- Formal verification: < 30 minutes

### Resource Usage
- Memory: Bounded by system limits
- Disk: Audit trails grow linearly
- CPU: Parallel builds when possible
- Network: Minimal (local-first)

---

## SUPPORT & ESCALATION

### Self-Service
1. Check `bob-shell/README.md` for command usage
2. Review `BOB_TRUST_DEED_V1.md` for principles
3. Search `.continuity/decisions.json` for precedents
4. Run `bob-policy query` for policy questions

### Escalation Path
1. **Level 1:** Command help (`--help` flag)
2. **Level 2:** Repository documentation
3. **Level 3:** Continuity decision log
4. **Level 4:** Human review (for violations)

---

## VERSION HISTORY

### v1.0 (2026-07-25)
- Initial operational contract
- Six SovereignShell commands
- Trust Deed v1.0 compliance
- Continuity integration

---

## SIGNATURES

**Established By:** Ahmad Ali Parr (ahmedparr93@gmail.com)  
**Implemented By:** BOB (Claude 3.7 Sonnet)  
**Repository:** bobs control repo  
**Effective Date:** 2026-07-25

**Contract Seal:**
```
SHA256(BOB_OPERATIONAL_CONTRACT:v1.0:2026-07-25)
```

---

## APPENDIX A: COMMAND REFERENCE

Quick reference for all SovereignShell commands:

```bash
# Build
bob-build <component> [--verify] [--profile=dev|prod|audit]

# Test
bob-test [suite] [--deterministic] [--coverage]

# Audit
bob-audit <component> [--format=json|text]

# Policy
bob-policy query "<rule>" [--explain]

# Deploy
bob-deploy <target> [--validate] [--seal]

# Proof
bob-proof <theorem> [--backend=lean4|ada|coq]
```

---

## APPENDIX B: TRUST DEED CHECKLIST

Before any deployment:

- [ ] No Python in production paths
- [ ] No stub implementations
- [ ] Complete documentation headers
- [ ] All tests passing
- [ ] Audit records generated
- [ ] Policy compliance verified
- [ ] Formal proofs (if required)
- [ ] Cryptographic seals generated
- [ ] Continuity decisions logged

---

**END OF OPERATIONAL CONTRACT**

*"Evidence or Silence. Complete or Nothing. Verified or Rejected."*