docs: add lens reviewers and fan-out docs [doc-updater]

README.md

@@ -102,7 +102,7 @@ Human gate        Human gate                              Human merge
 
 1. **Refine**: Agents analyze the task, research the codebase, produce requirements. Reviewers validate. Human approves before planning.
 2. **Plan**: Architect recommends approach, task planner breaks it into discrete tasks with acceptance criteria, risk analyst flags concerns. Human approves before any code is written.
-3. **Implement**: Coder writes code, tester writes tests and runs linters/type-checkers, documenter updates docs. Code and contract reviewers provide line-level feedback. Cycles continue until all checks pass and BRC consensus is reached.
+3. **Implement**: Coder writes code, tester writes tests and runs linters/type-checkers, documenter updates docs. Code and contract reviewers provide line-level feedback; advisory security and concurrency lens reviewers add targeted cross-file analysis. Cycles continue until all checks pass and BRC consensus is reached.
 4. **PR**: Orchestrator auto-creates the PR from plan metadata. Only a human can merge via GitHub UI.
 
 Within each phase, specialized agents run concurrently via BRC (enabled by default for refine, plan, and implement). Here's what a completed pipeline looks like:
@@ -133,6 +133,7 @@ Within each phase, specialized agents run concurrently via BRC (enabled by defau
 │   ✓ coder                                     │
 │   ✓ tester  ✓ documenter                      │
 │   ✓ reviewer_code  ✓ reviewer_contract        │
+│   ✓ reviewer_security  ✓ reviewer_concurrency │
 │   [1h11m]                                     │
 ╚═══════════════════════════════════════════════╝
     │

docs/guides/sdlc-pipeline.md

@@ -941,14 +941,23 @@ Contracts can override phase defaults via the `phase_configs` field:
         }
       ],
       "max_review_cycles": 5,
-      "human_review_mechanism": "PR_REVIEW"
+      "human_review_mechanism": "PR_REVIEW",
+      "reviewer_code": {
+        "parallel": true
+      }
     }
   }
 }
 ```
 
 When `phase_configs.{phase}.checks` is specified, it completely replaces the default checks for that phase.
 
+The `reviewer_code` object exposes a single knob:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `parallel` | bool | `true` | Fan out `reviewer_code` subagents in parallel. Set `false` to force sequential review for cost or quota reasons. |
+
 ### Writing Custom Checks
 
 Custom checks can be configured per-repository in `~/.config/egg/repositories.yaml` (see above) or by adding check definitions to `shared/egg_contracts/phase_defaults.py`.
@@ -1197,7 +1206,7 @@ egg-contract add-feedback --question "What is the expected request volume?" --qu
 ## Concurrent Execution Mode
 
 Concurrent execution mode enables all agents (coder, tester, documenter, reviewer_code,
-reviewer_contract) to run simultaneously during the implement phase,
+reviewer_contract, reviewer_security, reviewer_concurrency) to run simultaneously during the implement phase,
 collaborating via a polling-based message bus hosted by the orchestrator.
 
 ### Configuration

docs/reference/agent-roles.md

@@ -10,7 +10,7 @@ Every agent role belongs to one of five categories. Categories enable dynamic te
 |----------|---------|-------|
 | **EXECUTION** | Produce artifacts (code, tests, docs) | `coder`, `tester`, `documenter` |
 | **ANALYSIS** | Analyze tasks and plan work | `refiner`, `architect`, `task_planner`, `risk_analyst` |
-| **REVIEW** | Validate quality and correctness | `reviewer_code`, `reviewer_contract`, `reviewer_refine`, `reviewer_plan`, `reviewer_agent_design` |
+| **REVIEW** | Validate quality and correctness | `reviewer_code`, `reviewer_contract`, `reviewer_refine`, `reviewer_plan`, `reviewer_agent_design`, `reviewer_security`, `reviewer_concurrency` |
 | **UTILITY** | Cross-cutting support tasks | `autofixer`, `conflict_resolver` |
 | **INTERFACE** | Pipeline health and monitoring | `inspector`, `overseer` |
 
@@ -30,8 +30,10 @@ Use `get_roles_by_category(AgentCategory.REVIEW)` to dynamically query roles by
 | `coder` | Execution | Implement | No | — |
 | `tester` | Execution | Implement | Yes (with `documenter`) | coder |
 | `documenter` | Execution | Implement | Yes (with `tester`) | coder |
-| `reviewer_code` | Review | Implement | Yes (with `reviewer_contract`) | coder, tester |
-| `reviewer_contract` | Review | Implement | Yes (with `reviewer_code`) | coder, tester |
+| `reviewer_code` | Review | Implement | Yes (with `reviewer_contract`, `reviewer_security`, `reviewer_concurrency`) | coder, tester |
+| `reviewer_contract` | Review | Implement | Yes (with `reviewer_code`, `reviewer_security`, `reviewer_concurrency`) | coder, tester |
+| `reviewer_security` | Review | Implement | Yes (with `reviewer_code`, `reviewer_contract`, `reviewer_concurrency`) | coder, tester |
+| `reviewer_concurrency` | Review | Implement | Yes (with `reviewer_code`, `reviewer_contract`, `reviewer_security`) | coder, tester |
 | `autofixer` | Utility | Any | Yes | — |
 | `conflict_resolver` | Utility | Any | Yes | — |
 | `inspector` | Interface | Any | — | — (health checks) |
@@ -238,6 +240,8 @@ each surface so reviewers know to keep them in sync.
 - Allowed writes: `.egg-state/reviews/`, `.egg-state/agent-outputs/`
 - Blocked: All source, docs, tests, contracts, drafts
 
+**Subagent fan-out**: On large diffs (`files_changed > 10` OR `loc_added + loc_removed > 500`), `reviewer_code` fans out into Claude Agent SDK subagents — one per implement-phase task partition (capped at 6, with a 5-minute / 300-second per-subagent wall-clock timeout that NACKs the partition on overrun). Each subagent reviews its slice; the parent aggregates findings and emits the single ACK/NACK. A mandatory cross-partition consistency pass runs regardless of whether fan-out fires. Fan-out can be forced sequential via `phase_configs.implement.reviewer_code.parallel = false` (default: `true`).
+
 **Outputs**:
 - `.egg-state/reviews/{identifier}-implement-reviewer_code-review.json` — Verdict file
 
@@ -252,6 +256,32 @@ each surface so reviewers know to keep them in sync.
 **Outputs**:
 - `.egg-state/reviews/{identifier}-implement-reviewer_contract-review.json` — Verdict file
 
+### `reviewer_security`
+
+**Purpose**: ADVISORY security-lens reviewer. Focuses exclusively on cross-file security invariants that a general code reviewer may miss: cross-file allowlist mismatches, handler-vs-validator path mismatches, information-disclosure and authorization-bypass patterns, uncommitted-artifact/Dockerfile-symlink mismatches, secret leakage, and OWASP top-10 patterns spanning multiple changed files.
+
+**Criticality**: ADVISORY — NACKs block consensus informally but do not deadlock BRC until severity-tagged NACK signalling lands. Promotion to CRITICAL is intentionally deferred.
+
+**File access**:
+- Allowed writes: `.egg-state/reviews/`, `.egg-state/agent-outputs/`
+- Blocked: All source, docs, tests, contracts, drafts
+
+**Outputs**:
+- `.egg-state/reviews/{identifier}-implement-reviewer_security-review.json` — Verdict file
+
+### `reviewer_concurrency`
+
+**Purpose**: ADVISORY concurrency-lens reviewer. Focuses exclusively on concurrency invariants: race conditions, deadlocks, shared-state mutation without synchronization, async-context leakage, retry-storm patterns, resource-cleanup ordering bugs, and BRC-protocol invariants (send→wait ordering, cursor threading, heartbeat-stall windows).
+
+**Criticality**: ADVISORY — same deferral rationale as `reviewer_security` above.
+
+**File access**:
+- Allowed writes: `.egg-state/reviews/`, `.egg-state/agent-outputs/`
+- Blocked: All source, docs, tests, contracts, drafts
+
+**Outputs**:
+- `.egg-state/reviews/{identifier}-implement-reviewer_concurrency-review.json` — Verdict file
+
 ## Utility Roles
 
 ### `autofixer`