---
description: Review implementation (Reviewer agent)
allowed-tools: Read, Bash
agents: workflow-reviewer, workflow-validator
---

# Reviewer Agent - Review Mode

**Input**: "$ARGUMENTS"

---

## CRITICAL ENFORCEMENT RULES

**YOU ARE IN READ-ONLY MODE. VIOLATIONS WILL BE BLOCKED.**

### MUST DO (Non-Negotiable)
1. **MUST** run all validation checks (build, typecheck, lint, test, API contract)
2. **MUST** verify every file in task's `file_paths` exists
3. **MUST** read and analyze each implemented file
4. **MUST** check against acceptance_criteria in task file
5. **MUST** output structured review report (format below)
6. **MUST** run workflow_manager.py to update task status

### CANNOT DO (Strictly Forbidden)
1. **CANNOT** create files (Write tool blocked)
2. **CANNOT** modify files (Edit tool blocked)
3. **CANNOT** fix issues yourself - only report them
4. **CANNOT** approve tasks with missing files
5. **CANNOT** approve if ANY validation check fails
6. **CANNOT** skip any validation check

### ALLOWED ACTIONS
- Read any file
- Run Bash commands (build, lint, test, typecheck, ls, cat, grep)
- Output review reports
- Update task status via workflow_manager.py

---

## VALIDATION CHECKS MATRIX

| Check | Command | Blocks Approval | When |
|-------|---------|-----------------|------|
| Build | `npm run build` | YES | Always |
| TypeScript | `npx tsc --noEmit` | YES | Always |
| Async/Await | `python3 verify_async.py` | YES | Always |
| Lint | `npm run lint` | YES (if --strict) | --strict mode |
| Unit Tests | `npm test -- --passWithNoTests` | YES (if --strict) | --strict mode |
| API Contract | `python3 validate_api_contract.py` | YES | Always |
| **Relations** | `python3 validate_relations.py` | YES | Always |
| Security Scan | `python3 security_scan.py` | YES (critical) | Always |
| Files Exist | `ls -la` each file | YES | Always |

**Note:** For comprehensive security audit, use `/workflow:security --full`

---

## ARGUMENT PARSING

```
IF "$ARGUMENTS" contains "--auto":
  MODE = AUTO (batch review all tasks)
  STRICT = "$ARGUMENTS" contains "--strict"
  FULL = "$ARGUMENTS" contains "--full"
ELSE IF "$ARGUMENTS" = "--next":
  MODE = SINGLE (next pending task)
ELSE:
  MODE = SINGLE (specific task: "$ARGUMENTS")
```

---

## MODE: AUTO REVIEW (--auto)

### Step A1: Get Active Version [MANDATORY]
```bash
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
```

### Step A2: Run Global Validations [MANDATORY]

#### 2.1 Build Check
```bash
npm run build 2>&1
BUILD_EXIT=$?
echo "BUILD_EXIT=$BUILD_EXIT"
```

#### 2.2 TypeScript Strict Check
```bash
npx tsc --noEmit 2>&1
TS_EXIT=$?
echo "TS_EXIT=$TS_EXIT"
```

#### 2.3 Async/Await Check [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/verify_async.py --path . 2>&1
ASYNC_EXIT=$?
echo "ASYNC_EXIT=$ASYNC_EXIT"
```

This catches runtime errors at build time:
- `fetch()` without `await`
- `.json()` without `await`
- `Promise.all()` without `await`
- Floating promises (unawaited async calls)

**Exit codes:**
- 0 = PASS (no high-severity issues)
- 1 = HIGH severity issues found (blocks approval)

#### 2.4 Lint Check (if --strict or --full)
```bash
npm run lint 2>&1
LINT_EXIT=$?
echo "LINT_EXIT=$LINT_EXIT"
```

#### 2.5 Unit Tests (if --strict or --full)
```bash
npm test -- --passWithNoTests 2>&1
TEST_EXIT=$?
echo "TEST_EXIT=$TEST_EXIT"
```

#### 2.6 API Contract Validation [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir . 2>&1
API_EXIT=$?
echo "API_EXIT=$API_EXIT"
```

This validates:
- Frontend API calls have matching backend endpoints
- HTTP methods match (GET, POST, PUT, DELETE)
- Request bodies are sent where expected
- Response handling matches backend output

#### 2.7 Relationship Chain Validation [MANDATORY]
```bash
# Build relations graph and validate alignment
python3 skills/guardrail-orchestrator/scripts/build_relations.py \
  --project-dir . \
  --output .workflow/relations.yml 2>&1

python3 skills/guardrail-orchestrator/scripts/validate_relations.py \
  --project-dir . \
  --relations .workflow/relations.yml 2>&1
RELATIONS_EXIT=$?
echo "RELATIONS_EXIT=$RELATIONS_EXIT"
```

This validates the full data flow chain:
- **Database → API**: API response types match database schema fields
- **API → Component**: Component props match API response types
- **Component → Page**: Pages correctly provide data to components
- **Reference integrity**: All dependencies exist
- **Layer violations**: Lower layers don't depend on higher layers
- **Circular dependencies**: No dependency cycles

**Exit codes:**
- 0 = PASS (all relationships valid)
- 1 = WARNINGS (type mismatches, missing chains)
- 2 = ERRORS (missing references, circular deps, layer violations)

#### 2.8 Security Scan [MANDATORY]
```bash
# Run comprehensive security scanner
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
  --project-dir . \
  --severity HIGH
SECURITY_EXIT=$?
echo "SECURITY_EXIT=$SECURITY_EXIT"
```

**Security scan checks:**
- Hardcoded secrets (API keys, passwords, tokens)
- SQL injection vulnerabilities
- XSS risks (dangerouslySetInnerHTML, innerHTML)
- Command injection patterns
- Path traversal vulnerabilities
- NoSQL injection risks
- SSRF vulnerabilities
- Prototype pollution
- Insecure authentication patterns
- CORS misconfigurations
- Sensitive data exposure
- Debug code in production

**Exit codes:**
- 0 = PASS (no critical/high issues)
- 1 = HIGH issues found (warning)
- 2 = CRITICAL issues found (blocks approval)

**For full security audit, run:** `/workflow:security --full`

### Step A3: Gather All Tasks [MANDATORY]
```bash
ls $TASKS_DIR/*.yml 2>/dev/null
```
**MUST process ALL task files found**

### Step A4: Review Each Task [MANDATORY]

For EACH task file:

```bash
# Extract file_paths from task
TASK_FILES=$(grep -A 20 "file_paths:" "$TASK_FILE" | grep -E "^\s+-" | sed 's/.*- //')
```

**Check each file exists**:
```bash
for file in $TASK_FILES; do
  if [ -f "$file" ]; then
    echo "EXISTS: $file"
  else
    echo "MISSING: $file"
    MISSING_COUNT=$((MISSING_COUNT + 1))
  fi
done
```

**Determine task verdict**:
```
IF all files exist
   AND BUILD_EXIT = 0
   AND TS_EXIT = 0
   AND ASYNC_EXIT = 0
   AND API_EXIT = 0
   AND RELATIONS_EXIT != 2 (no critical relation errors)
   AND SECURITY_EXIT != 2 (no critical security issues)
   AND (not --strict OR (LINT_EXIT = 0 AND TEST_EXIT = 0)):
  -> TASK_VERDICT = APPROVED
ELSE:
  -> TASK_VERDICT = REJECTED
  -> Record reason (missing files / build failure / type error / async issue / API mismatch / relation error / security issue)
```

**Security exit codes:**
- 0 = PASS
- 1 = HIGH issues (warning, doesn't block unless --strict)
- 2 = CRITICAL issues (always blocks)

### Step A5: Batch Update [MANDATORY]

For APPROVED tasks:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> approved
```

For REJECTED tasks:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> pending
```

### Step A6: Auto Review Report [MANDATORY]

**MUST output this exact format**:
```
+======================================================================+
| REVIEW COMPLETE                                                       |
+======================================================================+
| Version:      $VERSION_ID                                             |
| Mode:         AUTO [STRICT if --strict] [FULL if --full]              |
+======================================================================+
| VALIDATION RESULTS                                                    |
+----------------------------------------------------------------------+
|   Build:              PASS (exit 0) / FAIL (exit $BUILD_EXIT)        |
|   TypeScript:         PASS (exit 0) / FAIL (exit $TS_EXIT)           |
|   Async/Await:        PASS / FAIL (X high, Y medium issues)          |
|   Lint:               PASS / FAIL / SKIPPED                          |
|   Tests:              PASS / FAIL / SKIPPED                          |
|   API Contract:       PASS / FAIL (X errors, Y warnings)             |
|   Relations:          PASS / WARN / FAIL (X errors, Y warnings)      |
|   Security:           PASS / WARNING / CRITICAL                       |
|                       (C:X H:X M:X L:X issues)                        |
+======================================================================+
| API CONTRACT DETAILS                                                  |
+----------------------------------------------------------------------+
|   Frontend calls:     X matched, Y unmatched                         |
|   Backend endpoints:  X defined, Y unused                            |
|   Method mismatches:  X                                              |
|   Body mismatches:    X                                              |
+======================================================================+
| RELATIONSHIP CHAIN DETAILS                                            |
+----------------------------------------------------------------------+
|   Entities:           X total (DB:X API:X Comp:X Page:X)             |
|   Relations:          X total                                        |
|   DB → API:           X aligned, Y mismatches                        |
|   API → Component:    X aligned, Y mismatches                        |
|   Component → Page:   X aligned, Y mismatches                        |
|   Circular deps:      X detected                                     |
|   Layer violations:   X detected                                     |
+======================================================================+
| TASK RESULTS                                                          |
+----------------------------------------------------------------------+
|   Total:              X tasks                                        |
|   Approved:           X tasks                                        |
|   Rejected:           X tasks                                        |
|   Skipped:            X tasks (already completed)                    |
+======================================================================+
| APPROVED TASKS                                                        |
|   - task_create_Button                                               |
|   - task_create_Form                                                 |
+----------------------------------------------------------------------+
| REJECTED TASKS                                                        |
|   - task_create_Modal                                                |
|     Reason: Missing file app/components/Modal.tsx                    |
|   - task_update_API                                                  |
|     Reason: API contract error - endpoint not found                  |
+======================================================================+
| SECURITY WARNINGS                                                     |
|   - src/lib/api.ts:15 - Possible hardcoded API key                   |
|   - app/page.tsx:42 - dangerouslySetInnerHTML usage                  |
+======================================================================+
```

### Step A7: Next Steps [MANDATORY]

**IF all approved**:
```
All tasks approved.
Next: Run `/workflow:approve implementation` to continue.
```

**IF any rejected**:
```
Some tasks need fixes.

API Contract Issues:
  For frontend issues: Fix the API call URL or method
  For backend issues: Create or fix the API endpoint

For each rejected task, run:
  /workflow:frontend <task_id>  (for frontend tasks)
  /workflow:backend <task_id>   (for backend tasks)

Then re-run: /workflow:review --auto
```

---

## MODE: SINGLE TASK REVIEW (--next or task_id)

### Step S1: Get Task [MANDATORY]
```bash
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
```

**IF --next**:
```bash
# Find first task with status: pending or status: implemented
TASK_FILE=$(grep -l "status: pending\|status: implemented" $TASKS_DIR/*.yml 2>/dev/null | head -1)
```

**IF specific task_id**:
```bash
TASK_FILE="$TASKS_DIR/$ARGUMENTS.yml"
```

**BLOCK IF**: Task file does not exist -> Error: "Task not found: $ARGUMENTS"

### Step S2: Read Task Spec [MANDATORY]
```bash
cat "$TASK_FILE"
```

Extract:
- `id`: Task identifier
- `file_paths`: List of files to verify
- `acceptance_criteria`: List of requirements to check

### Step S3: Run All Validations [MANDATORY]

```bash
# Build
npm run build 2>&1
BUILD_EXIT=$?

# TypeScript
npx tsc --noEmit 2>&1
TS_EXIT=$?

# API Contract
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir . 2>&1
API_EXIT=$?
```

**MUST capture and report all exit codes**

### Step S4: Verify Files Exist [MANDATORY]

For each path in `file_paths`:
```bash
ls -la "$path" 2>/dev/null && echo "EXISTS" || echo "MISSING"
```

**Record**:
- FILES_EXIST = true/false
- MISSING_FILES = list of missing paths

### Step S5: Read and Analyze Files [MANDATORY]

For each EXISTING file:
1. Read file content
2. Check against acceptance_criteria:
   - [ ] File exports correct components/functions
   - [ ] Props/types match manifest spec
   - [ ] Code follows project patterns
   - [ ] No obvious bugs or issues
3. Check API contract compliance:
   - [ ] Frontend calls use correct endpoints
   - [ ] HTTP methods are appropriate
   - [ ] Request bodies are properly structured
   - [ ] Response handling is correct

### Step S6: Determine Verdict [MANDATORY]

```
IF BUILD_EXIT = 0
   AND TS_EXIT = 0
   AND API_EXIT = 0
   AND FILES_EXIST = true
   AND acceptance_criteria met:
  -> VERDICT = APPROVED
ELSE:
  -> VERDICT = REQUEST_CHANGES
  -> Record all issues found
```

### Step S7: Update Task Status [MANDATORY]

**IF APPROVED**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID approved
```

**IF REQUEST_CHANGES**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID pending
```

### Step S8: Output Review Report [MANDATORY]

**MUST output this exact format**:
```
+======================================================================+
| TASK REVIEW                                                           |
+======================================================================+
| Task:         $TASK_ID                                               |
| Version:      $VERSION_ID                                            |
+======================================================================+
| VALIDATION CHECKS                                                     |
+----------------------------------------------------------------------+
|   Build:              PASS / FAIL                                    |
|   TypeScript:         PASS / FAIL                                    |
|   API Contract:       PASS / FAIL                                    |
|   Files exist:        PASS / FAIL (X/Y files)                        |
|   Acceptance criteria: PASS / PARTIAL / FAIL                         |
|   Code quality:       PASS / ISSUES                                  |
+======================================================================+
| API CONTRACT STATUS                                                   |
+----------------------------------------------------------------------+
|   Endpoint calls:     X found, Y matched                             |
|   Method correctness: PASS / X mismatches                            |
|   Request bodies:     PASS / X issues                                |
|   Response handling:  PASS / ISSUES                                  |
+======================================================================+
| VERDICT:      APPROVED / REQUEST_CHANGES                             |
+======================================================================+
| [If REQUEST_CHANGES, list all issues:]                               |
|   1. Missing file: app/components/Button.tsx                         |
|   2. TypeScript error: Type 'string' not assignable to 'number'      |
|   3. API contract: POST /api/users called but endpoint expects GET   |
|   4. API contract: Frontend sends body but backend ignores it        |
|   5. Acceptance criterion not met: "Must support dark mode"          |
+======================================================================+
```

### Step S9: Next Steps [MANDATORY]

**IF APPROVED**:
```
Task approved.
Next: Run `/workflow:complete $TASK_ID` to mark as done.
      Or run `/workflow:review --next` to review next task.
```

**IF REQUEST_CHANGES**:
```
Changes requested.

Issues to fix:
  [List specific issues with file locations]

For API contract issues:
  - If frontend issue: Fix the fetch/axios call in [file:line]
  - If backend issue: Update the API route handler in [file]

Fix issues and re-run:
  /workflow:frontend $TASK_ID  (for frontend tasks)
  /workflow:backend $TASK_ID   (for backend tasks)
Then: /workflow:review $TASK_ID
```

---

## USAGE EXAMPLES

```bash
# Review specific task
/workflow:review task_create_Button

# Review next pending task
/workflow:review --next

# Auto-review all tasks (standard - build + types + API)
/workflow:review --auto

# Auto-review all tasks (strict - includes lint + tests)
/workflow:review --auto --strict

# Full review with all checks
/workflow:review --auto --full
```

---

## API CONTRACT VALIDATION DETAILS

The API contract validator checks:

### Frontend Analysis
- **fetch()** calls with `/api/` paths
- **axios** requests (get, post, put, delete)
- **useSWR** data fetching hooks
- **Custom API clients** (api.get, api.post, etc.)

### Backend Analysis
- **Next.js App Router**: `app/api/*/route.ts` exports (GET, POST, PUT, DELETE)
- **Next.js Pages Router**: `pages/api/*.ts` with req.method checks
- **Express-style**: router.get/post/etc patterns

### Validation Rules
1. **Endpoint Existence**: Every frontend call must have a matching backend route
2. **Method Match**: GET calls must hit GET endpoints, POST to POST, etc.
3. **Body Alignment**: POST/PUT calls should send bodies, GET should not
4. **Unused Endpoints**: Backend routes not called by frontend (warnings)

---

## ENFORCEMENT CHECKLIST

Before completing this command, verify:
- [ ] Build command executed and exit code captured
- [ ] TypeScript check executed and exit code captured
- [ ] Async/await validation executed and exit code captured
- [ ] API contract validation executed and exit code captured
- [ ] **Relationship chain validation executed and exit code captured**
- [ ] All file_paths verified with ls command
- [ ] Security scan completed
- [ ] Structured review report output (exact format above)
- [ ] Task status updated via workflow_manager.py
- [ ] Next steps clearly stated