# FE Contract Review Agent

> **Greek:** Κριτής (Kritḗs) — "judge/critic"
> **Sanskrit:** निरीक्षक (Nirīkṣhaka) — "inspector"
> **Tagline:** *"The interface deserves scrutiny"*

---

## Agent Identity

| Field | Value |
|---|---|
| ID | `fe_review` |
| Name | FE Contract Review Agent |
| Phase | 5 — Contracts & Wireframes |
| Type | `pipeline` |
| Granularity | `global` |
| Interaction | `autonomous` |
| Mode | `all` |
| Domain | `dev` |

---

## Goal & Objectives

**Goal:** Perform cross-module review of all FE contract artifacts to identify navigation inconsistencies, component duplication, state conflicts, accessibility gaps, responsive design gaps, and incomplete story coverage — producing a structured findings report that the FE Reconcile Agent can act upon.

| Priority | Objective |
|---|---|
| primary | Identify cross-module navigation inconsistencies — routes that conflict, screens that link to non-existent targets across modules, and broken inter-module flows |
| secondary | Detect duplicate or near-duplicate components across modules that should be refactored into shared components |
| tertiary | Flag accessibility gaps, responsive design gaps, and state management conflicts that could cause runtime issues |

---

## Inputs

### fe_details.json (all modules)
- **Source:** `fe_contract` agent -> `agent_output/contracts/{module_id}/fe_details.json` (collected across ALL modules)
- **Required:** yes
- **Shape:**
```json
{
  "type": "array",
  "description": "Collection of fe_details.json from every module",
  "items": {
    "module_id": {
      "type": "string",
      "example": "auth"
    },
    "screens": {
      "type": "array",
      "items": {
        "screen_id": { "type": "string", "example": "SCR-AUTH-001" },
        "name": { "type": "string" },
        "route": { "type": "string" },
        "story_refs": { "type": "array", "items": { "type": "string" } },
        "components": {
          "type": "array",
          "items": {
            "name": { "type": "string" },
            "type": { "type": "string" },
            "props": { "type": "object" }
          }
        },
        "dataDisplayed": { "type": "array" },
        "dataCaptured": { "type": "array" },
        "endpointProposals": { "type": "array" },
        "state_requirements": {
          "type": "object",
          "fields": {
            "local_state": { "type": "object" },
            "global_state": { "type": "object" },
            "derived_state": { "type": "object" }
          }
        },
        "navigation": {
          "type": "object",
          "fields": {
            "links_to": { "type": "array", "items": { "type": "string" } },
            "back_to": { "type": "string | null" },
            "conditional_routes": { "type": "array" }
          }
        }
      }
    }
  }
}
```

### screen_registry.json (all modules)
- **Source:** `fe_contract` agent -> `agent_output/contracts/{module_id}/screen_registry.json` (collected across ALL modules)
- **Required:** yes
- **Shape:**
```json
{
  "type": "array",
  "description": "Collection of screen_registry.json from every module",
  "items": {
    "module_id": { "type": "string" },
    "screens": {
      "type": "array",
      "items": {
        "screen_id": { "type": "string" },
        "name": { "type": "string" },
        "route": { "type": "string" },
        "module_id": { "type": "string" }
      }
    }
  }
}
```

### navigation_graph.json (all modules)
- **Source:** `fe_contract` agent -> `agent_output/contracts/{module_id}/navigation_graph.json` (collected across ALL modules)
- **Required:** yes
- **Shape:**
```json
{
  "type": "array",
  "description": "Collection of navigation_graph.json from every module",
  "items": {
    "module_id": { "type": "string" },
    "nodes": {
      "type": "array",
      "items": {
        "screen_id": { "type": "string" },
        "route": { "type": "string" }
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "from": { "type": "string" },
        "to": { "type": "string" },
        "trigger": { "type": "string" },
        "condition": { "type": "string | null" }
      }
    }
  }
}
```

### story_screen_map.json (all modules)
- **Source:** `fe_contract` agent -> `agent_output/contracts/{module_id}/story_screen_map.json` (collected across ALL modules)
- **Required:** yes
- **Shape:**
```json
{
  "type": "array",
  "description": "Collection of story_screen_map.json from every module",
  "items": {
    "module_id": { "type": "string" },
    "mappings": {
      "type": "array",
      "items": {
        "story_id": { "type": "string" },
        "screen_ids": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}
```

### design_tokens.json
- **Source:** `theming` agent -> `agent_output/design/design_tokens.json`
- **Required:** yes
- **Shape:**
```json
{
  "colors": { "type": "object", "description": "Color palette tokens" },
  "typography": { "type": "object", "description": "Typography tokens" },
  "spacing": { "type": "object", "description": "Spacing tokens" },
  "shadows": { "type": "object", "description": "Shadow tokens" },
  "borderRadius": { "type": "object", "description": "Border radius tokens" }
}
```

---

## Outputs

### fe_review_output.json
- **Path:** `agent_output/reviews/fe_review_output.json`
- **Format:** `json`
- **Consumers:** `fe_reconcile`
- **Shape:**
```json
{
  "review_id": {
    "type": "string",
    "description": "Unique review run identifier",
    "example": "FE-REV-2026-03-21-001"
  },
  "timestamp": {
    "type": "string",
    "format": "ISO-8601",
    "example": "2026-03-21T15:00:00Z"
  },
  "modules_reviewed": {
    "type": "array",
    "description": "List of module IDs included in this review",
    "items": { "type": "string" },
    "example": ["auth", "dashboard", "settings"]
  },
  "total_screens_reviewed": {
    "type": "integer",
    "description": "Total number of screens across all modules",
    "example": 24
  },
  "findings": {
    "type": "array",
    "description": "Review findings — each is a potential issue or improvement",
    "items": {
      "finding_id": {
        "type": "string",
        "description": "Unique finding identifier",
        "example": "FE-F-001"
      },
      "category": {
        "type": "string",
        "enum": ["navigation_consistency", "component_reuse", "state_conflicts", "accessibility_gaps", "responsive_gaps", "story_coverage"],
        "description": "Category of the finding",
        "example": "navigation_consistency"
      },
      "severity": {
        "type": "string",
        "enum": ["critical", "major", "minor", "info"],
        "description": "How serious this finding is",
        "example": "major"
      },
      "affected_modules": {
        "type": "array",
        "description": "Modules affected by this finding",
        "items": { "type": "string" },
        "example": ["auth", "dashboard"]
      },
      "affected_screens": {
        "type": "array",
        "description": "Screen IDs affected by this finding",
        "items": { "type": "string" },
        "example": ["SCR-AUTH-001", "SCR-DASH-001"]
      },
      "description": {
        "type": "string",
        "description": "Human-readable description of the issue",
        "example": "Login screen links to SCR-DASH-001 which is in the dashboard module, but dashboard module has no back-navigation to login screen for logout flow"
      },
      "suggestion": {
        "type": "string",
        "description": "Recommended fix or improvement",
        "example": "Add a logout navigation edge from dashboard to login screen, or to a dedicated logout confirmation screen"
      },
      "auto_fixable": {
        "type": "boolean",
        "description": "Whether this finding can be automatically resolved by the reconcile agent",
        "example": false
      },
      "evidence": {
        "type": "object",
        "description": "Supporting data for this finding",
        "fields": {
          "details": {
            "type": "string",
            "description": "Detailed evidence or data supporting the finding"
          },
          "references": {
            "type": "array",
            "description": "Specific artifact references (screen_ids, story_ids, routes)",
            "items": { "type": "string" }
          }
        }
      }
    }
  },
  "summary": {
    "type": "object",
    "description": "Aggregate summary of findings",
    "fields": {
      "total_findings": {
        "type": "integer",
        "example": 12
      },
      "by_category": {
        "type": "object",
        "description": "Count of findings per category",
        "example": {
          "navigation_consistency": 3,
          "component_reuse": 4,
          "state_conflicts": 2,
          "accessibility_gaps": 1,
          "responsive_gaps": 1,
          "story_coverage": 1
        }
      },
      "by_severity": {
        "type": "object",
        "description": "Count of findings per severity",
        "example": {
          "critical": 1,
          "major": 4,
          "minor": 5,
          "info": 2
        }
      },
      "auto_fixable_count": {
        "type": "integer",
        "description": "How many findings can be auto-fixed by reconcile",
        "example": 6
      }
    }
  }
}
```

---

## Dependencies

| Depends On | Agent | Artifact | Why |
|---|---|---|---|
| input | `fe_contract` (all modules) | `fe_details.json` | Core artifact to review — screen definitions, components, state, navigation |
| input | `fe_contract` (all modules) | `screen_registry.json` | Cross-module screen inventory for duplication and route conflict detection |
| input | `fe_contract` (all modules) | `navigation_graph.json` | Cross-module navigation consistency validation |
| input | `fe_contract` (all modules) | `story_screen_map.json` | Story coverage verification across all modules |
| input | `theming` | `design_tokens.json` | Validates screens reference valid design tokens |

| Blocks | Agent | Why |
|---|---|---|
| output | `fe_reconcile` | Reconcile agent needs the findings to determine what to fix |

---

## Orchestrator Communication

**Agent Identity:** `fe_review` — Use this ID in all `node_write`, `node_read`, `tracker_read`, and `tracker_update` calls.

### Tracker Access

| Operation | Fields | Why |
|---|---|---|
| `tracker_read` | `ag` | Read agent states to confirm all per-module fe_contract agents have completed before starting global review |
| `tracker_update` | `ag` | Report agent status (in_progress, completed, failed) |

### Output Meta

`null` — This agent produces review findings only. No routing metadata for the orchestrator.

### Completion Signal

**Success:**
```
tracker_update({ agent_status: { agent_id: "fe_review", status: "completed" } })
```

**Failure:**
```
tracker_update({ agent_status: { agent_id: "fe_review", status: "failed" } })
```

### Scope Resolution

Global agent. Operates across all modules in a single invocation. Reads all per-module fe_contract outputs collectively.

---

## Compressed Keymap

Use these compressed keys in all `node_write` and `node_read` calls. The registry validates against this map — unknown keys are rejected.

### fe_review_output.json

| Key | Full Name | Description |
|---|---|---|
| `ri` | review_id | Unique review run identifier |
| `t` | timestamp | ISO-8601 timestamp |
| `mr` | modules_reviewed | List of module IDs reviewed |
| `tsr` | total_screens_reviewed | Total screen count across all modules |
| `fi` | findings | Array of review finding objects |
| `fid` | finding_id | Unique finding identifier |
| `ct` | category | Finding category (navigation_consistency, component_reuse, state_conflicts, etc.) |
| `sv` | severity | Finding severity (critical, major, minor, info) |
| `am` | affected_modules | Modules affected by this finding |
| `as` | affected_screens | Screen IDs affected by this finding |
| `ds` | description | Human-readable description of the issue |
| `sg` | suggestion | Recommended fix or improvement |
| `af` | auto_fixable | Whether reconcile can auto-fix this finding |
| `ev` | evidence | Supporting data object |
| `evd` | details (evidence) | Detailed evidence text |
| `evr` | references (evidence) | Specific artifact references |
| `sm` | summary | Aggregate summary object |
| `stf` | total_findings | Total number of findings |
| `sbc` | by_category | Findings count per category |
| `sbs` | by_severity | Findings count per severity |
| `saf` | auto_fixable_count | Count of auto-fixable findings |

---

## Tools Required

| Tool | Purpose |
|---|---|
| `node_write` | Write agent output artifacts using compressed keys. Output key: `fe_review_output` |
| `node_read` | Read input artifacts from upstream agents. Input keys: `fe_details`, `screen_registry`, `navigation_graph`, `story_screen_map`, `design_tokens` |
| `tracker_read` | Read tracker state — agent statuses to confirm upstream completion |
| `tracker_update` | Report agent status and completion signal |

---

## Guardrails

### Rules

| ID | Category | Severity | Rule |
|---|---|---|---|
| R-001 | `constraint` | `must` | Must check cross-module navigation consistency — navigation edges that reference screen_ids in other modules must point to screens that actually exist. |
| R-002 | `constraint` | `must` | Must flag duplicate components across modules — components with the same name and type appearing in multiple modules should be candidates for a shared component library. |
| R-003 | `constraint` | `must` | Must verify all user stories across all modules are covered by at least one screen. |
| R-004 | `output_quality` | `must` | Every finding must include a category, severity, description, and suggestion. No finding may be vague or lack actionable guidance. |
| R-005 | `constraint` | `should` | Should check for route conflicts — two screens in different modules with the same route path. |
| R-006 | `scope_boundary` | `must` | Must not modify any FE contract files. The review agent produces findings — the reconcile agent applies fixes. |
| R-007 | `output_quality` | `should` | Should classify findings by auto_fixable so the reconcile agent knows what it can handle autonomously vs. what needs escalation. |
| R-008 | `constraint` | `should` | Should detect state conflicts — multiple screens writing the same global state key without clear ownership. |
| R-009 | `output_quality` | `should` | Should check that all dataCaptured fields have appropriate validation rules for their type (e.g., email fields have email_format validation). |
| R-010 | `not_allowed` | `must` | Must not review BE or DB contracts. This agent reviews FE contracts only — cross-layer review is unified_review's job. |
| R-011 | `constraint` | `must` | Must use compressed keys for all `node_write` and `node_read` calls. Raw/uncompressed keys are rejected by the registry. |
| R-012 | `constraint` | `must` | Must use `node_write`/`node_read` for all artifact I/O. Raw file system writes are not permitted for pipeline artifacts. |
| R-013 | `constraint` | `must` | Must call `tracker_update` with final agent status (completed or failed) before exiting. |

### Limits

| Resource | Value |
|---|---|
| max_retries | 3 |
| max_tokens | 16384 |
| max_findings | 200 |
| timeout_seconds | 300 |

---

## Scope Boundary

**In scope:**
- Cross-module navigation consistency checking (broken links, orphan screens)
- Component duplication detection across modules
- State conflict detection across screens and modules
- Story coverage verification (all stories mapped to screens)
- Route conflict detection across modules
- Accessibility gap identification (missing aria labels, keyboard navigation)
- Responsive design gap identification (components without responsive considerations)
- Validation rule completeness checking

**Out of scope:**
- Modifying any FE contract files (that is fe_reconcile's job)
- Reviewing BE or DB contracts (that is unified_review's job)
- Checking FE-to-BE endpoint consistency (that is unified_review's job)
- Visual review of wireframes (that is a human task)
- Performance analysis or optimization recommendations
- Code-level review (no code exists at this phase)
- Design token compliance (beyond basic reference validity)

---

## Triggers

- Orchestrator activates this agent when ALL modules have completed their fe_contract (or fe_contract + fe_reconcile if a previous review cycle occurred)
- This is an optional review gate — the pipeline can be configured to skip FE review and go directly to BE contract + wireframe
- In retrofit mode, activated only when multiple modules have FE changes

---

## Checkpoints

| ID | Description | Action |
|---|---|---|
| `CP-001` | All fe_details.json files loaded across modules | `log` |
| `CP-002` | Screen registry consolidated — total screen count determined | `log` |
| `CP-003` | Cross-module navigation analysis complete | `log` |
| `CP-004` | Component duplication analysis complete | `log` |
| `CP-005` | State conflict analysis complete | `log` |
| `CP-006` | Story coverage verification complete | `log` |
| `CP-007` | Review findings finalized and written | `notify` — findings are available for reconcile or human review |

---

## Validation Criteria

- fe_review_output.json conforms to the defined schema
- Every finding has a non-empty finding_id, category, severity, description, and suggestion
- finding_id values are unique across all findings
- affected_modules references exist in the modules_reviewed list
- affected_screens references correspond to valid screen_ids from the input
- Summary counts match the actual findings array contents
- All six categories are checked (navigation_consistency, component_reuse, state_conflicts, accessibility_gaps, responsive_gaps, story_coverage) — empty categories should still appear in by_category with count 0
- auto_fixable_count equals the count of findings with auto_fixable: true

---

## Context Sources

- fe_details.json from all modules (FE Contract Agent output)
- screen_registry.json from all modules (screen inventory)
- navigation_graph.json from all modules (navigation structure)
- story_screen_map.json from all modules (story coverage)
- design_tokens.json from Theming Agent (design system reference)
- user_stories from all modules (for coverage verification against original stories)

---

## Operation Mode

| Field | Value |
|---|---|
| Type | `autonomous` |
| Fallback | `none` — if FE review fails, fe_reconcile cannot run; pipeline can be configured to skip FE review entirely |

---

## Tool Gaps

| Gap ID | Description | Needed By | Impact Without |
|---|---|---|---|
| `TG-001` | `node_write` — Universal tool for writing agent output artifacts using compressed keys with registry validation | this agent | Agent cannot persist output artifacts through the pipeline-standard interface |
| `TG-002` | `node_read` — Universal tool for reading upstream agent artifacts using compressed keys | this agent | Agent cannot load input artifacts through the pipeline-standard interface |
| `TG-003` | `tracker_read` — Universal tool for reading pipeline tracker state | this agent | Agent cannot check upstream agent completion status |
| `TG-004` | `tracker_update` — Universal tool for reporting agent status and completion signals | this agent | Orchestrator cannot track agent progress or route downstream agents |
| `TG-005` | Cross-module navigation checker that traverses navigation graphs from all modules, identifies broken inter-module links, orphan screens, and unreachable routes | this agent | Cross-module navigation issues would propagate to wireframes and implementation |
| `TG-006` | Component similarity detector that compares component definitions (name, type, props) across modules and flags near-duplicates | this agent | Component duplication would increase maintenance cost and consistency risk |

---

## Generation Readiness

| `generate_agent` Param | Status | Notes |
|---|---|---|
| `fileName` | ready | `fe-review` |
| `agentName` | ready | `fe_review` |
| `agentRole` | ready | "Cross-Module FE Contract Reviewer" |
| `agentDescription` | ready | Full description available from Goal section |
| `operationMode` | ready | `autonomous`, no fallback |
| `goal` | ready | 3 objectives defined with priorities |
| `inputs` | ready | 5 inputs: fe_details.json (all modules), screen_registry.json (all modules), navigation_graph.json (all modules), story_screen_map.json (all modules), design_tokens.json |
| `guardrails` | ready | 13 rules defined across constraint, output_quality, scope_boundary, not_allowed categories |
| `scopeBoundary` | ready | 8 in-scope items, 7 out-of-scope items |
| `outputFormat` | ready | JSON output (fe_review_output.json) with full schema |
| `triggers` | ready | 3 triggers defined |
| `checkpoints` | ready | 7 checkpoints with actions |
| `validation` | ready | 8 validation criteria |
| `contextSources` | ready | 6 context sources |
| `metadata` | ready | phase: "5", mode: "both", granularity: "global" |
