# Global Navigation Agent

> **Greek:** Pyxis (Pyxis) -- "compass"
> **Sanskrit:** Disha (Disa) -- "direction/guidance"
> **Tagline:** *"Every page has a path"*

---

## Agent Identity

| Field | Value |
|---|---|
| ID | `global_navigation` |
| Name | Global Navigation Agent |
| Phase | 7 -- Global Architecture |
| Type | `pipeline` |
| Granularity | `global` |
| Interaction | `autonomous` |
| Mode | `all` |
| Domain | `dev` |

---

## Goal & Objectives

**Goal:** Merge all per-module FE flow graphs into a site-wide navigation structure, resolving route conflicts, building coherent navigation hierarchies, and defining auth-gated route policies that provide a unified user experience across all modules.

| Priority | Objective |
|---|---|
| primary | Produce a global_navigation.json with a complete route registry covering all modules, with zero duplicate or conflicting routes |
| secondary | Build a coherent primary and secondary navigation hierarchy that organizes all modules' screens into a logical site-wide menu structure |
| tertiary | Define breadcrumb rules and auth-gated route policies (public, authenticated, role-based) across the entire application |

---

## Inputs

### fe_flow.json (ALL modules)
- **Source:** `fe_flow` -> `agent_output/architecture/{module_id}/fe_flow.json` (for each module)
- **Required:** yes
- **Shape:**
```json
{
  "module_id": "string -- module identifier",
  "nodes": [
    {
      "node_id": "string",
      "type": "string -- 'screen' | 'modal' | 'redirect' | 'error'",
      "screen_ref": "string | null",
      "route": "string | null",
      "label": "string",
      "is_entry_point": "boolean",
      "requires_auth": "boolean",
      "required_roles": ["string"]
    }
  ],
  "entry_points": [
    {
      "node_id": "string",
      "route": "string",
      "is_default": "boolean",
      "auth_required": "boolean"
    }
  ],
  "guards": [
    {
      "guard_id": "string",
      "type": "string",
      "applies_to": ["string"],
      "config": {
        "auth_required": "boolean",
        "role_required": ["string"],
        "redirect_on_fail": "string"
      }
    }
  ]
}
```

### fe_details.json (ALL modules)
- **Source:** `fe_contract` -> `agent_output/contracts/{module_id}/fe_details.json` (for each module)
- **Required:** yes
- **Shape:**
```json
{
  "module_id": "string -- module identifier",
  "screens": [
    {
      "screen_id": "string",
      "screen_name": "string",
      "route": "string"
    }
  ],
  "navigation_graph": {
    "nodes": ["string"],
    "edges": [
      {
        "from": "string",
        "to": "string",
        "trigger": "string"
      }
    ]
  }
}
```

---

## Outputs

### global_navigation.json
- **Path:** `agent_output/architecture/global/global_navigation.json`
- **Format:** `json`
- **Consumers:** `architect_reconcile`, `impl_prep`, `fe_impl`
- **Shape:**
```json
{
  "generated_at": "string -- ISO-8601 timestamp",
  "total_routes": "number -- total routes across all modules",
  "total_modules": "number -- number of modules in navigation",
  "primary_nav": [
    {
      "nav_id": "string -- unique nav item identifier (e.g., 'NAV-001')",
      "label": "string -- display label (e.g., 'Dashboard', 'Users', 'Billing')",
      "route": "string -- URL route for this nav item",
      "module": "string -- module_id this nav item belongs to",
      "icon": "string | null -- icon identifier (e.g., 'dashboard', 'users', 'credit-card')",
      "order": "number -- display order in navigation (1-based)",
      "auth_required": "boolean -- whether authentication is needed",
      "required_roles": ["string -- roles that can see this nav item (empty = all authenticated)"],
      "children": [
        {
          "nav_id": "string -- child nav item identifier",
          "label": "string -- child display label",
          "route": "string -- child URL route",
          "icon": "string | null",
          "order": "number",
          "auth_required": "boolean",
          "required_roles": ["string"]
        }
      ]
    }
  ],
  "secondary_nav": {
    "user_menu": [
      {
        "nav_id": "string",
        "label": "string -- e.g., 'Profile', 'Settings', 'Logout'",
        "route": "string",
        "icon": "string | null",
        "auth_required": "boolean"
      }
    ],
    "footer_nav": [
      {
        "nav_id": "string",
        "label": "string -- e.g., 'Terms', 'Privacy', 'Help'",
        "route": "string"
      }
    ],
    "utility_nav": [
      {
        "nav_id": "string",
        "label": "string -- e.g., 'Notifications', 'Search'",
        "route": "string | null",
        "action": "string | null -- 'open_panel' | 'navigate'"
      }
    ]
  },
  "breadcrumb_rules": [
    {
      "rule_id": "string -- unique rule identifier",
      "route_pattern": "string -- route pattern this rule applies to (e.g., '/users/:id')",
      "breadcrumbs": [
        {
          "label": "string -- breadcrumb label (can use :param syntax for dynamic labels)",
          "route": "string -- breadcrumb link route",
          "is_dynamic": "boolean -- whether the label is computed from route params or data"
        }
      ]
    }
  ],
  "route_registry": [
    {
      "route": "string -- full URL route (e.g., '/dashboard', '/users/:id')",
      "module_id": "string -- module this route belongs to",
      "screen_ref": "string -- screen_id from fe_flow",
      "label": "string -- human-readable page name",
      "auth_required": "boolean",
      "required_roles": ["string"],
      "params": [
        {
          "name": "string -- parameter name (e.g., 'id')",
          "type": "string -- 'string' | 'number' | 'uuid'",
          "required": "boolean"
        }
      ],
      "is_entry_point": "boolean -- whether this is a module entry point",
      "parent_route": "string | null -- parent route for hierarchical navigation"
    }
  ],
  "auth_routes": {
    "public": ["string -- routes accessible without authentication"],
    "authenticated": ["string -- routes requiring authentication (any role)"],
    "role_based": {
      "admin": ["string -- routes requiring admin role"],
      "user": ["string -- routes requiring user role"],
      "manager": ["string -- routes requiring manager role"]
    }
  },
  "route_conflicts": [
    {
      "conflict_id": "string -- unique conflict identifier",
      "route": "string -- the conflicting route",
      "modules_involved": ["string -- module_ids claiming this route"],
      "resolution": "string -- how the conflict was resolved (e.g., 'prefixed with module name')",
      "resolved_routes": ["string -- the resolved route paths"]
    }
  ]
}
```

---

## Dependencies

| Depends On | Agent | Artifact | Why |
|---|---|---|---|
| input | `fe_flow` (all modules) | `fe_flow.json` | Provides screen graphs, entry points, routes, and guards for each module |
| input | `fe_contract` (all modules) | `fe_details.json` | Provides screen names and navigation graphs for labeling and hierarchy |
| barrier | ALL Phase 6 agents | All modules must complete Phase 6 before this global agent starts |

| Blocks | Agent | Why |
|---|---|---|
| output | `architect_reconcile` | Reconcile needs global navigation to build complete architecture |
| output | `impl_prep` | Impl prep agent needs navigation structure to generate layout components |

---

## Orchestrator Communication

### Agent Identity

This agent's ID is `global_navigation`. Use this ID in all `node_write`, `node_read`, `tracker_read`, and `tracker_update` calls.

### Tracker Access

| Direction | Compressed Keys | Purpose |
|---|---|---|
| read | (none) | Global agent -- does not read `md.a` |
| write | `ag` | Report agent status (completed/failed) |

### Output Meta

This agent does not produce routing/coordination metadata. `output_meta: null`.

### Completion Signal

- **On success:** `tracker_update(agent_id: "global_navigation", status: "completed")`
- **On failure:** `tracker_update(agent_id: "global_navigation", status: "failed", add_intervention: { id: "...", agent_id: "global_navigation", type: "error", message: "..." })`

### Scope Resolution

Global agent -- does NOT read `md.a`. Reads all modules' per-module artifacts in a single pass.

```
1. node_read(agent_id: "global_navigation", input_key: "fe_flow_all")
2. node_read(agent_id: "global_navigation", input_key: "fe_details_all")
3. Process all modules → merge routes and build navigation hierarchy
4. node_write(agent_id: "global_navigation", output_key: "global_navigation", data: {...})
5. tracker_update(agent_id: "global_navigation", status: "completed")
```

---

## Compressed Keymap

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

### Output: `global_navigation.json`

| Key | Full Name | Description |
|---|---|---|
| `ga` | generated_at | ISO-8601 timestamp |
| `tr` | total_routes | Total routes across all modules |
| `tm` | total_modules | Number of modules in navigation |
| `pn` | primary_nav | Primary navigation items |
| `pn.ni` | nav_id | Unique nav item ID (e.g., 'NAV-001') |
| `pn.lb` | label | Display label (e.g., 'Dashboard') |
| `pn.rt` | route | URL route for this nav item |
| `pn.md` | module | Module ID this nav item belongs to |
| `pn.ic` | icon | Icon identifier (e.g., 'dashboard') |
| `pn.or` | order | Display order (1-based) |
| `pn.ar` | auth_required | Whether authentication is needed |
| `pn.rr` | required_roles | Roles that can see this nav item |
| `pn.ch` | children | Child nav items |
| `pn.ch.ni` | nav_id | Child nav item ID |
| `pn.ch.lb` | label | Child display label |
| `pn.ch.rt` | route | Child URL route |
| `pn.ch.ic` | icon | Child icon |
| `pn.ch.or` | order | Child display order |
| `pn.ch.ar` | auth_required | Child auth required |
| `pn.ch.rr` | required_roles | Child required roles |
| `sn` | secondary_nav | Secondary navigation sections |
| `sn.um` | user_menu | User menu items |
| `sn.um.ni` | nav_id | User menu item ID |
| `sn.um.lb` | label | Display label (e.g., 'Profile') |
| `sn.um.rt` | route | URL route |
| `sn.um.ic` | icon | Icon identifier |
| `sn.um.ar` | auth_required | Whether auth needed |
| `sn.fn` | footer_nav | Footer navigation items |
| `sn.fn.ni` | nav_id | Footer nav item ID |
| `sn.fn.lb` | label | Display label (e.g., 'Terms') |
| `sn.fn.rt` | route | URL route |
| `sn.un` | utility_nav | Utility navigation items |
| `sn.un.ni` | nav_id | Utility nav item ID |
| `sn.un.lb` | label | Display label (e.g., 'Notifications') |
| `sn.un.rt` | route | URL route |
| `sn.un.ac` | action | open_panel / navigate |
| `br` | breadcrumb_rules | Breadcrumb rule definitions |
| `br.ri` | rule_id | Unique rule identifier |
| `br.rp` | route_pattern | Route pattern this rule applies to |
| `br.bc` | breadcrumbs | Breadcrumb chain |
| `br.bc.lb` | label | Breadcrumb label |
| `br.bc.rt` | route | Breadcrumb link route |
| `br.bc.id` | is_dynamic | Whether label is computed from data |
| `rr` | route_registry | Complete route registry |
| `rr.rt` | route | Full URL route |
| `rr.mi` | module_id | Module this route belongs to |
| `rr.sr` | screen_ref | Screen ID from fe_flow |
| `rr.lb` | label | Human-readable page name |
| `rr.ar` | auth_required | Whether auth needed |
| `rr.rl` | required_roles | Required roles |
| `rr.pm` | params | Route parameters |
| `rr.pm.nm` | name | Parameter name |
| `rr.pm.tp` | type | string / number / uuid |
| `rr.pm.rq` | required | Whether required |
| `rr.ie` | is_entry_point | Whether this is a module entry point |
| `rr.pr` | parent_route | Parent route for hierarchical navigation |
| `ar` | auth_routes | Auth-based route classification |
| `ar.pb` | public | Routes accessible without auth |
| `ar.au` | authenticated | Routes requiring auth (any role) |
| `ar.rb` | role_based | Role-specific route access |
| `ar.rb.ad` | admin | Admin-only routes |
| `ar.rb.us` | user | User-role routes |
| `ar.rb.mg` | manager | Manager-role routes |
| `rc` | route_conflicts | Detected route conflicts |
| `rc.ci` | conflict_id | Unique conflict identifier |
| `rc.rt` | route | The conflicting route |
| `rc.mi` | modules_involved | Module IDs claiming this route |
| `rc.rs` | resolution | How the conflict was resolved |
| `rc.rr` | resolved_routes | The resolved route paths |

---

## Tools Required

| Tool | Purpose | Exists? |
|---|---|---|
| `node_write` | Write global_navigation output via registry-validated compressed keys. Agent calls `node_write(agent_id: "global_navigation", output_key: "global_navigation", data: {...})`. | Pending |
| `node_read` | Read upstream artifacts (fe_flow_all, fe_details_all). Agent calls `node_read(agent_id: "global_navigation", input_key: "fe_flow_all")`. | Pending |
| `tracker_read` | Read pipeline state. Agent calls `tracker_read(agent_id: "global_navigation", fields: [...])`. | Pending |
| `tracker_update` | Report completion/failure. Agent calls `tracker_update(agent_id: "global_navigation", status: "completed")`. | Pending |

---

## Guardrails

### Rules

| ID | Category | Severity | Rule |
|---|---|---|---|
| R-001 | `constraint` | `must` | No duplicate routes across modules -- every route in route_registry must be unique |
| R-002 | `constraint` | `must` | Must build a coherent navigation hierarchy -- every module must be reachable from primary or secondary nav |
| R-003 | `constraint` | `must` | Must handle auth-gated routes -- every route must be classified as public, authenticated, or role-based |
| R-004 | `constraint` | `must` | All route conflicts must be detected and resolved with documented resolution strategy |
| R-005 | `output_quality` | `must` | Primary nav must have a logical ordering (dashboard first, settings last, etc.) |
| R-006 | `data_handling` | `must` | Every route in route_registry must reference a valid module_id and screen_ref |
| R-007 | `scope_boundary` | `should` | Breadcrumb rules should cover all navigable routes with dynamic label support |
| R-008 | `output_quality` | `should` | Navigation items should have icon suggestions for common categories |
| R-009 | `not_allowed` | `must` | Must not invent routes not present in any module's fe_flow.json |
| R-010 | `constraint` | `should` | Route parameters should specify type (string, number, uuid) for validation |
| R-011 | `output_quality` | `should` | Auth routes classification should match the guards defined in per-module fe_flow |
| R-012 | `constraint` | `must` | Must use compressed keys as defined in the Compressed Keymap section for all `node_write` / `node_read` calls. Never use expanded/full key names. |
| R-013 | `constraint` | `must` | Must use `node_write` to write output and `node_read` to read upstream artifacts. Must not use raw file writes, generic file_writer, or any other method. |
| R-014 | `constraint` | `must` | Must call `tracker_update(agent_id: "global_navigation", status: "completed")` before exiting on success. Must call `tracker_update(agent_id: "global_navigation", status: "failed", add_intervention: {...})` before exiting on failure. |

### Limits

| Resource | Value |
|---|---|
| max_retries | 3 |
| max_tokens | 32000 |
| max_primary_nav_items | 15 |
| max_nav_depth | 3 |

---

## Scope Boundary

**In scope:**
- Merging all modules' routes into a global route registry
- Detecting and resolving route conflicts across modules
- Building primary and secondary navigation hierarchies
- Defining breadcrumb rules for all navigable routes
- Classifying routes by auth requirements (public, authenticated, role-based)
- Assigning navigation ordering and icons

**Out of scope:**
- Modifying per-module fe_flow.json (read-only)
- Implementing navigation components (Phase 10 FE implementation)
- Defining middleware or security policies (global_security agent's job)
- Building global service registry (global_services agent's job)
- Designing visual navigation layouts or styles

---

## Triggers

- Orchestrator detects that ALL modules have completed Phase 6 (barrier cleared)
- Can run in PARALLEL with global_services, global_middleware (independent inputs)
- Triggered once (global granularity)

---

## Checkpoints

| ID | Description | Action |
|---|---|---|
| `CP-001` | All modules' fe_flow.json and fe_details.json loaded | `log` |
| `CP-002` | Route registry compiled from all modules | `log` |
| `CP-003` | Route conflict detected between modules | `notify` |
| `CP-004` | Navigation hierarchy built -- primary and secondary nav defined | `log` |
| `CP-005` | Auth route classification complete | `log` |
| `CP-006` | Global navigation output generated and schema-validated | `notify` |

---

## Validation Criteria

- Every route from every module's fe_flow.json appears in route_registry
- No duplicate routes in route_registry (unique route + method combinations)
- Every route is classified in auth_routes (public, authenticated, or role_based)
- All route conflicts are documented with resolutions
- Primary nav covers all modules (every module has at least one nav entry)
- Breadcrumb rules cover all routes with depth > 1
- All nav_ids are unique across primary_nav, secondary_nav, and children
- Route parameters have defined types
- Output JSON passes schema validation
- Navigation hierarchy depth does not exceed max_nav_depth limit

---

## Context Sources

- fe_flow.json from all modules (screen graphs, routes, entry points, guards)
- fe_details.json from all modules (screen names, navigation graphs)
- Common navigation patterns in web applications

---

## Operation Mode

| Field | Value |
|---|---|
| Type | `autonomous` |
| Fallback | `none` |

---

## Tool Gaps

| Gap ID | Description | Needed By | Impact Without |
|---|---|---|---|
| `TG-001` | Route conflict detector that identifies duplicate, overlapping, and ambiguous routes across modules | this agent | Route conflicts cause runtime errors; manual detection unreliable for many modules |
| `TG-002` | Navigation hierarchy builder that infers parent-child relationships from flat route lists | this agent | Must manually organize routes; risk of poor navigation structure |
| `TG-003` | `node_write` MCP tool not yet built | this agent | Cannot write output with registry validation -- blocked |
| `TG-004` | `node_read` MCP tool not yet built | this agent | Cannot read upstream artifacts with field enforcement -- blocked |
| `TG-005` | `tracker_read` MCP tool not yet built | this agent | Cannot read pipeline state -- blocked |
| `TG-006` | `tracker_update` MCP tool not yet built | this agent | Cannot report completion -- blocked |

---

## Generation Readiness

| `generate_agent` Param | Status | Notes |
|---|---|---|
| `fileName` | ready | `global-navigation` |
| `agentName` | ready | `global_navigation` |
| `agentRole` | ready | Site-Wide Navigation Builder |
| `agentDescription` | ready | Merges all module routes into a unified navigation structure with conflict resolution |
| `operationMode` | ready | autonomous, no fallback |
| `goal` | ready | Three objectives defined with clear priorities |
| `inputs` | ready | All modules' fe_flow.json and fe_details.json |
| `guardrails` | ready | 14 rules covering constraints, quality, data handling, scope, universal tools, and completion signal |
| `scopeBoundary` | ready | 6 in-scope items, 5 out-of-scope items |
| `outputFormat` | ready | JSON output with full shape for global_navigation.json |
| `triggers` | ready | Barrier-triggered after all modules complete Phase 6; parallel with other Phase 7 agents |
| `checkpoints` | ready | 6 checkpoints covering loading, registry, conflicts, hierarchy, and output |
| `validation` | ready | 10 validation criteria |
| `contextSources` | ready | 3 context sources listed |
| `metadata` | ready | Phase 7, global, autonomous, both modes |
