# Anti-Hallucination Integration Overview

## System Architecture

```
┌─────────────────────────────────────────────────────────┐
│                 TASK CONSTRAINT LAYER                   │
│              (@backlog/tasks/task-XXX/)              │
│                                                      │
│  What enforces boundaries (PRD+spec+review)        │
│  • task-XXX/prd.md - Goal, scope, success criteria │
│  • task-XXX/spec.md - Architecture, constraints, edge cases │
│  • task-XXX/review.md - What changed, what skipped      │
│                                                      │
│  MANDATORY before ANY work                           │
└─────────────────────────────────────────────────────────┘
                                ▲ │
                      ENFORCEMENT │ │ VALIDATION
                                │ ▼
┌─────────────────────────────────────────────────────────┐
│              MEMORY SUPPORT LAYER                    │
│           (@.opencode/memory/)                       │
│                                                      │
│  Templates and patterns (supportive role)             │
│  • _templates/ - PRD, spec, review templates       │
│  • development-guidelines.md - Project patterns        │
│  • architecture-decisions.md - Design constraints     │
│  • research/ - Findings (task-linked only)         │
│                                                      │
│  Reference for task compliance                        │
└─────────────────────────────────────────────────────────┘
                                ▲ │
                    TEMPLATING │ │ PATTERNS
                                │ ▼
┌─────────────────────────────────────────────────────────┐
│               AGENT EXECUTION                      │
│                                                      │
│  All tools validate task constraints first          │
│  • edit/write - Abort without task spec            │
│  • git commit - Abort without completed review       │
│  • All agents - Must validate against PRD criteria │
│                                                      │
│  Zero tolerance for constraint violations           │
└─────────────────────────────────────────────────────────┘
```

## Anti-Hallucination Architecture

| Layer                | Directory                  | Lifespan  | Purpose              | Enforcement    |
| -------------------- | -------------------------- | --------- | -------------------- | -------------- |
| **Task Constraints** | `@backlog/tasks/task-XXX/` | Session   | Mandatory boundaries | **Absolute**   |
| **Memory Support**   | `@.opencode/memory/`       | Permanent | Templates & patterns | **Supportive** |
| **Agent Execution**  | All agents                 | Session   | Implementation       | **Validated**  |

## MANDATORY Workflow (No Exceptions)

### 1. Task Creation (Entry Point)

```
/task-with-spec "feature description"
↓
Creates: @backlog/tasks/task-XXX/{prd,spec,review}.md
↓
Templates from: @.opencode/memory/_templates/
↓
Success criteria: Measurable checkboxes required
```

### 2. Task Validation (Pre-Work)

```
ANY COMMAND EXECUTION
↓
Check: Task exists? (@backlog/tasks/task-XXX/)
↓
Read: PRD+spec+review files
↓
Validate: Success criteria measurable?
↓
Abort: If any validation fails
```

### 3. Bounded Execution (During Work)

```
AGENT WORK (ANY COMMAND)
↓
Continuously validate against:
- PRD scope boundaries
- Spec constraints
- Success criteria
- Edge cases
↓
Stop: If any constraint violation detected
↓
Document: All work in task review.md
```

### 4. Completion Validation (Post-Work)

```
/complete-task task-XXX
↓
Validate: All success criteria marked complete?
↓
Check: Review.md filled with "what changed, what skipped"?
↓
Update: Task status → Done
↓
Commit: Only after validation passes
```

## Anti-Hallucination Enforcement Points

### 1. Tool Level Enforcement

- **edit/write tools**: Abort without completed task spec
- **git commit**: Abort without completed review.md
- **all agents**: Must validate against PRD success criteria
- **violation**: Immediate task failure

### 2. Command Level Enforcement

- **All 30+ commands**: Require task context before execution
- **No exceptions**: Commands abort without task validation
- **Bounded operation**: Work only within PRD+spec constraints
- **Compliance checking**: Continuous validation during work

### 3. Template Level Enforcement

- **PRD template**: Requires measurable success criteria
- **Spec template**: Requires constraints and edge cases
- **Review template**: Requires "what changed, what skipped, inconsistencies"
- **Missing fields**: Templates cannot be submitted incomplete

## File Organization (Anti-Hallucination Structure)

```
.opencode/
├── memory/
│   ├── _templates/
│   │   ├── task-prd.md      # Goal, scope, success criteria
│   │   ├── task-spec.md     # Architecture, constraints, edge cases
│   │   └── task-review.md   # What changed, what skipped
│   ├── development-guidelines.md  # Project patterns (reference)
│   └── research/               # Task-linked findings only
├── AGENTS.md                   # ANTI-HALLUCINATION RULE (Priority #2)
└── INTEGRATION_OVERVIEW.md    # This file

backlog/
└── tasks/
    ├── task-001/
    │   ├── prd.md      # MANDATORY boundaries
    │   ├── spec.md     # MANDATORY constraints
    │   └── review.md   # MANDATORY validation
    └── task-002/        # Same structure

(Git history)                # Execution audit trail
```

## Command Integration (All 30+ Commands)

### Core Commands (Task Creation)

- `/task-with-spec` → Creates 3 mandatory files
- `/complete-task` → Validates completion before done

### Implementation Commands (Task-Bounded)

- `/research-and-implement` → Research within task constraints
- `/plan` → Plan within task boundaries
- `/quick-build` → Even quick tasks need constraints
- `/plan-and-build` → Planning requires task setup

### Specialized Commands (Task-Focused)

- `/design/*` → Design within task scope only
- `/fix/*` → Fixes with task tracking only
- `/skill/*` → Skills for task requirements only
- `/review/*` → Reviews within task boundaries only

### Utility Commands (Task-Validated)

- `/commit` → Task-validated commits only
- `/status` → Task compliance status only
- `/handoff` → Task-bounded handoffs only
- `/context` → Task-focused context analysis only

### Improvement Commands (Task-Constrained)

- `/brainstorm` → Task-constrained ideas only
- `/improve` → Task-specific prompt improvements only
- `/think` → Task-bounded thinking only

## Global Rules (ANTI-HALLUCINATION PRIORITY)

### Priority Hierarchy

1. **Security constraints** (always first)
2. **ANTI-HALLUCINATION RULE** (overrides everything except security)
3. User explicit requests
4. Base prompt behaviors
5. Global rules (this file)
6. Project conventions
7. Context information

### MANDATORY WORKFLOW

1. **Before ANY code work**: Must read task PRD + spec
2. **During work**: Must verify against spec constraints continuously
3. **After work**: Must complete review.md with validation details
4. **NO EXCEPTIONS**: Tools must verify task files exist before execution

## Brutal Reality

**This system prevents hallucination through:**

- **Mandatory task creation** - No work without 3 files
- **Continuous validation** - Every action checked against constraints
- **Bounded execution** - Work only within PRD+spec boundaries
- **Completion enforcement** - No task done without validation
- **Tool integration** - All abort on constraint violations

**No more free-form AI operations. Every command serves task constraints first, last, and always.**

---

**Last Updated:** November 21, 2025  
**Status:** ✅ ANTI-HALLUCINATION SYSTEM COMPLETE  
**Decision:** Task constraints mandatory before any AI work
