SENTINEL - Adversarial Reviewer

SENTINEL is the adversarial reviewer. It runs in a fresh, ephemeral Coder workspace for each evaluation to eliminate accumulated bias. SENTINEL reviews security, test coverage, adherence to CONTRACT.md, and code quality. Using a different LLM provider than FORGE creates adversarial review - the reviewer's blind spots differ from the writer's.

plan_mode: true

SENTINEL runs with plan_mode: true which allocates more thinking tokens for thorough review. This is critical for catching subtle security and logic issues.

Architecture

┌─────────────────────────────────────────────────────────────┐
│ SENTINEL Workspace (fresh per evaluation)                    │
│                                                              │
│  ┌────────────────┐     ┌──────────────────────────────────┐│
│  │ Coder Agent    │────▶│ openflows-harness                ││
│  │ (LLM Session)  │     │ - dispatch read (get task)       ││
│  └────────────────┘     │ - status get (track phase)       ││
│                          │ - pr review (read diff)          ││
│                          │ - review write (blocking comments)││
│                          └──────────────────────────────────┘│
│                                      │                        │
│                                      ▼                        │
│                              ┌─────────────┐                 │
│                              │    Redis    │                 │
│                              │ SharedStore │                 │
│                              └─────────────┘                 │
└─────────────────────────────────────────────────────────────┘

Review Process

Handoff received - FORGE writes handoff.md via harness; SENTINEL reads it
Plan review - Reads CONTRACT.md and PLAN.md; writes CONTRACT.md response: AGREED / CHANGES_REQUESTED
Segment evaluation - After each FORGE commit, evaluates diff; writes segment-N-eval.md
Final review - Holistic review of entire branch; writes final-review.md (APPROVED / CHANGES_REQUESTED)
GitHub PR comments - Posts blocking comments directly on PR via GitHub MCP

Evaluation Criteria (5 Dimensions)

Dimension	What SENTINEL Checks
Correctness	Logic matches spec; edge cases handled; no off-by-one errors
Security	Input validation; no secrets in logs; no SQL injection; auth checks
Test Coverage	Unit tests for new logic; integration tests for API changes; property-based tests for algorithms
Standards	Code style (rustfmt/prettier); naming conventions; error handling patterns; documentation
No Regressions	Existing tests pass; no broken APIs; backward compatibility maintained

Output Artifacts

Artifact	When	Content
`CONTRACT.md`	Plan phase	AGREED / CHANGES_REQUESTED with specific feedback
`segment-N-eval.md`	Per segment	APPROVED / REJECTED with line-level comments
`final-review.md`	Pre-merge	APPROVED / CHANGES_REQUESTED - unblocks VESSEL
GitHub PR review	Continuous	Blocking comments on specific lines; security labels

Configuration

json

{
  "agents": {
    "sentinel": {
      "provider": "openai",
      "model": "gpt-4.1",
      "coder_module": "codex",
      "active": true,
      "instances": 1,
      "plan_mode": true,
      "skills": ["security-audit", "test-coverage"],
      "mcps": ["github-mcp"]
    }
  }
}

Adversarial routing matters

FORGE and SENTINEL must use different model families (e.g., FORGE on Anthropic, SENTINEL on OpenAI). Running both on the same provider defeats the purpose of adversarial review. See Model Routing.

Workspace Lifecycle

SENTINEL workspaces are ephemeral per evaluation:

NEXUS provisions fresh workspace for evaluation
SENTINEL clones repo at PR commit
Runs review against CONTRACT.md
Writes evaluation to PR and SharedStore
Workspace destroyed immediately after

This eliminates bias accumulation and ensures each review starts from a clean slate.

Hook System

Hook	Purpose
`session_start.sh`	Loads CONTRACT.md, PR diff, handoff context
`pre_bash_guard.sh`	Read-only mode - blocks write commands
`post_write_lint.sh`	Validates review artifacts are well-formed
`stop_require_artifact.sh`	Requires evaluation artifact before stop

Rejection Loop Detection

NEXUS tracks consecutive rejections for the same segment. After SENTINEL_REJECTION_LIMIT (default 3), the ticket is escalated to AwaitingHuman with a STATUS.json blocker.