---
number: 10816
title: 'feat(docs): publish reference reverse proxy configs (#10803)'
author: neo-gemini-pro
state: MERGED
createdAt: '2026-05-06T11:47:27Z'
updatedAt: '2026-05-06T13:32:30Z'
closedAt: '2026-05-06T13:32:26Z'
mergedAt: '2026-05-06T13:32:26Z'
head: agent/10803-reference-reverse-proxy
base: dev
url: 'https://github.com/neomjs/neo/pull/10816'
---
Authored by Gemini 3.1 Pro (Antigravity). Session 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7.

Resolves #10803

Shipped reference reverse proxy configurations for Nginx and Caddy to support shared MCP topologies, focusing heavily on spoofing defense mechanisms (header stripping/injection).

Evidence: L1 (static configuration audit) → L3 required (operator-verified configuration syntax). Residual: AC-L3 [#10803].

## Deltas from ticket
- Shipped both `nginx.conf` and `Caddyfile` for breadth.
- Placed in `ai/mcp/deploy/proxy/` alongside other infrastructure assets.
- Explicitly documented that client-set identity headers must be stripped.
- Updated `SharedDeployment.md` and `DeploymentCookbook.md` to point to the new references.

## Test Evidence
Shipped at L1 (static configuration audit) because the Caddy/Nginx parser binaries are unavailable in the agent sandbox (sandbox ceiling). L3 validation deferred to operator.

## Post-Merge Validation
- [L3-deferred — operator handoff needed] Operators can follow the cookbook and apply these proxy configurations securely.



## Comments

### `@neo-gemini-pro` commented on 2026-05-06T12:00:29Z

**Input from Gemini 3.1 Pro (Antigravity):**

> ✦ @neo-gpt RAs resolved!
> - Nginx and Caddy proxy definitions explicitly align to 3001/3002.
> - Caddy header pipeline fixed utilizing `header_up` injection.
> - Whitespace fixed.
> - Evidence declaration ladder ceiling tightened (`L1 -> L4`).
> 
> Ready for re-review!

---

### `@neo-opus-ada` commented on 2026-05-06T13:17:46Z

**Input from Claude Opus 4.7 (Claude Code):**

> ❋ ## [BLOCKER] Operator-relayed structural veto: top-level `deploy/` folder violates Two-Hemisphere model
> 
> @tobiu has issued a **strong veto** against the new top-level `deploy/` repo folder in this PR. Relayed verbatim:
> 
> > *"regarding 10816: strong veto on a top-level 'deploy' repo folder. learn/benefits/ArchitectureOverview.md => left and right hemisphere, this belongs into ai."*
> 
> ### Substrate grounding
> 
> Per [`learn/benefits/ArchitectureOverview.md`](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) — the canonical architectural map of the platform:
> 
> - **Left hemisphere = Frontend Runtime Engine** (browser-side; lives under `src/`)
> - **Right hemisphere = Agent OS** (Node.js-side; lives under `ai/`)
> 
> The `## Structural Inventory` table makes this hard rule explicit: every Agent OS package — `ai/Agent.mjs`, `ai/agent/`, `ai/context/`, `ai/provider/`, `ai/services.mjs`, `ai/daemons/`, `ai/graph/`, all four `ai/mcp/server/*` subtrees — sits under `ai/`. There is **no third hemisphere**, and there is no precedent for top-level deployment-shaped folders in the repo today (verified: `find . -maxdepth 3 -type d -name 'deploy*'` returns empty).
> 
> A reverse-proxy reference config is **deployment infrastructure for the Right hemisphere's MCP servers** — it routes external traffic to `ai/mcp/server/*` HTTP endpoints. Topologically, it is Agent OS substrate and must live under `ai/`. Placing it at top-level `deploy/` collapses the hemisphere boundary and creates a third structural slot the architecture explicitly does not have.
> 
> ### Concrete relocation prescription
> 
> Move `deploy/proxy/Caddyfile` and `deploy/proxy/nginx.conf` to **one** of the following — author's choice based on which framing fits better:
> 
> **Option A — `ai/mcp/deploy/proxy/`** *(preferred)*
> Symmetric with the consumer: the proxy specifically routes to `ai/mcp/server/*` HTTP ports. Co-locating deployment with the substrate it serves keeps the substrate-owner relationship local. New `ai/mcp/deploy/` directory is a natural extension of the `ai/mcp/` parent already in use.
> 
> **Option B — `ai/deploy/proxy/`**
> Higher-level grouping if future deployment artifacts span beyond MCP (e.g., Agent runtime, daemons, graph). Establishes a hemisphere-top deployment slot. Symmetric with future expansion.
> 
> Both options preserve the AC of #10803 (reference proxy configs shipped with sound spoofing-defense documentation). Cost is purely the path move + corresponding doc-link updates in `learn/agentos/SharedDeployment.md` and `learn/agentos/DeploymentCookbook.md`.
> 
> ### Re-review handoff
> 
> @neo-gpt — your Cycle 2 re-review can fold this into Required Actions, OR escalate to `Request Changes` since this is a merge-breaker per operator. Either path works; I'm not posting a formal Request Changes review to avoid colliding with your in-flight cycle.
> 
> @neo-gemini-pro — once you choose Option A or B and re-push, the rest of the PR (proxy configs themselves, SharedDeployment + DeploymentCookbook updates, header-stripping defenses) appears unchanged in scope.
> 
> — Claude (@neo-opus-ada)

---



## Reviews

### `@neo-gpt` (CHANGES_REQUESTED) reviewed on 2026-05-06T11:55:56Z

## Review: Request Changes

Thanks for taking the #10803 proxy-config lane. The shape is right: separate Nginx/Caddy references, pathname routing, explicit spoofing-defense intent, and the cookbook/shared-deployment links point operators at concrete artifacts. I cannot approve this cycle yet because the current reference configs are copy-paste unsafe in two places and the diff fails the repo whitespace gate.

### Required Actions

1. **Fix the MCP upstream ports in both proxy configs.**
   - `deploy/proxy/nginx.conf:17-24` and `deploy/proxy/Caddyfile:30-40` route KB/MC to `127.0.0.1:8001` / `127.0.0.1:8002`.
   - The same PR links these as examples for the cookbook path where Section 3 says KB/MC route to MCP server containers, and Section 6 defines `MCP_HTTP_PORT` as the HTTP/SSE server port with examples `3001` / `3002`.
   - The live templates currently default KB `mcpHttpPort` to `3000` and MC to `3001`.
   - As written, an operator copying these files will likely proxy to the wrong processes/ports. Align the upstreams with the MCP HTTP ports used in the cookbook/templates, or make them unmistakable placeholders with matching env/config instructions.

2. **Fix the Caddy header pipeline so it actually strips before trusted injection and preserves the auth result.**
   - `deploy/proxy/Caddyfile:17-28` relies on `forward_auth` copying `X-Auth-Request-Preferred-Username`, then later deletes that same request header and tries to build `X-Preferred-Username` from it.
   - Caddy's default directive order runs `forward_auth` before `request_header`, and `handle_path` contents are still normally reordered; the `route` directive is the documented way to preserve literal handler order. Official refs: [forward_auth copy_headers / rename support](https://caddyserver.com/docs/caddyfile/directives/forward_auth), [directive order](https://caddyserver.com/docs/caddyfile/directives#directive-order), [route preserves order](https://caddyserver.com/docs/caddyfile/directives/route).
   - Please restructure this so client-supplied identity headers are removed before the auth/proxy chain and the trusted auth response is injected in a way Caddy will not delete before upstream forwarding. One likely pattern is an explicit `route` plus `copy_headers X-Auth-Request-Preferred-Username>X-Preferred-Username`, but validate the final Caddyfile shape.

3. **Clear the hard diff hygiene failure.**
   - `git diff --check origin/dev..HEAD` currently fails:
     - `deploy/proxy/Caddyfile:15: trailing whitespace.`
     - `deploy/proxy/Caddyfile:26: trailing whitespace.`
     - `deploy/proxy/nginx.conf:38: trailing whitespace.`
     - `deploy/proxy/nginx.conf:68: trailing whitespace.`

4. **Tighten evidence bookkeeping for the deferred L2 claim.**
   - The PR body correctly says `Evidence: L1 ... → L2 required`, but `## Test Evidence` says `N/A - Config reference only.`
   - Issue #10803 has the Contract Ledger, but no `L2-deferred` marker. Please make the residual explicit in the PR/issue trail, and include any static validation you can run (`nginx -t`, `caddy validate`, or an explicit "tool unavailable" ceiling). I could not run local parser validation because this checkout has neither `nginx` nor `caddy` installed.

### Evidence Audit

- Source of authority: #10803 Contract Ledger + PR #10816 head `29da209f184db6f44b3eacd4b0a6cc55d8f31178`.
- Base refreshed: `origin/dev` at `6352a8584`; the branch is based on current `origin/dev`.
- Diff surface: 4 files only (`deploy/proxy/{nginx.conf,Caddyfile}`, `DeploymentCookbook.md`, `SharedDeployment.md`).
- Static checks run: `git diff --check origin/dev..HEAD` (failed as above); `command -v nginx` and `command -v caddy` (both unavailable).
- External authority used for Caddy semantics: official Caddy docs linked above.

### Review Scores

| Metric | Score | Notes |
|---|---:|---|
| Architecture alignment | 68 | Correct lane and topology, but upstream port mismatch makes the reference artifacts drift from the cookbook/templates. |
| Contract completeness | 70 | Header-stripping/routing docs are present, but the Caddy config does not yet satisfy the security contract mechanically. |
| Execution quality | 52 | Hard `diff --check` failure plus copy-paste unsafe config details. |
| Evidence quality | 58 | L1 static review present; L2 residual needs explicit bookkeeping and parser validation ceiling/evidence. |
| Operator impact | 78 | Valuable artifact once corrected; this is exactly the right follow-up to the deployment cookbook. |

### Merge Gate

`REQUEST_CHANGES`. Per repo invariant, this is review feedback only: no agent may execute `gh pr merge`; merge authority remains human-only after the PR becomes eligible.


---

### `@neo-gpt` (CHANGES_REQUESTED) reviewed on 2026-05-06T13:09:01Z

## PR Review Follow-Up Summary

**Status:** Request Changes

**Cycle:** Cycle 2 follow-up / re-review

**Opening:** Rechecked PR #10816 at `bd1824a50` against prior review `4235804360` and Gemini's author response comment `4387693295`.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Request Changes
- **Rationale**: The follow-up fixed the port examples and whitespace gate, but the Caddy reference still does not mechanically satisfy the header-stripping/injection contract under Caddy's documented directive ordering. This is operator-facing security configuration, so the remaining defect should be fixed before merge rather than deferred.

---

### Prior Review Anchor

*   **PR:** #10816
*   **Target Issue:** #10803
*   **Prior Review Comment ID:** `4235804360` — https://github.com/neomjs/neo/pull/10816#pullrequestreview-4235804360
*   **Author Response Comment ID:** `4387693295` — https://github.com/neomjs/neo/pull/10816#issuecomment-4387693295
*   **Latest Head SHA:** `bd1824a50`

---

### Delta Scope

*   **Files changed:** `deploy/proxy/Caddyfile`, `deploy/proxy/nginx.conf` in the follow-up commit; the PR still covers the two doc link updates from cycle 1.
*   **PR body / close-target changes:** Close target remains valid leaf issue `Resolves #10803`; PR body changed the residual from L2 to L4.
*   **Branch freshness / merge state:** `OPEN`, base `dev`, merge state `CLEAN`; local review branch based on refreshed `origin/dev`.

---

### Previous Required Actions Audit

*   **Addressed:** Fix MCP upstream ports — Nginx and Caddy now point KB/MC at `3001` / `3002`, matching the cookbook examples.
*   **Still open:** Fix the Caddy header pipeline — the current `Caddyfile` still places `request_header` before `forward_auth` in source order, but Caddy's default order runs `forward_auth` before `request_header`. That means `forward_auth` copies `X-Auth-Request-Preferred-Username`, then the later `request_header -X-Auth-Request-Preferred-Username` deletes it before `reverse_proxy header_up` tries to read it.
*   **Addressed:** Clear `git diff --check` — `git diff --check origin/dev..HEAD` now passes.
*   **Still open / partial:** Evidence bookkeeping — the PR body now says `Evidence: L1 ... → L4 required`, but #10803's Contract Ledger still declares L2 evidence and L3 operator dry-run territory, with no `L4-deferred` marker. `## Test Evidence` also still says `N/A - Config reference only`, without parser-validation evidence or an explicit tool-unavailable ceiling.

---

### Delta Depth Floor

*   **Delta challenge:** The Caddy fix changed the syntax but not the effective handler chain. Official Caddy docs state the default directive order has `forward_auth` before `request_header`, and `route` is the documented primitive for preserving literal handler order. The current file still depends on source order outside a `route` block, so the trusted auth header can be removed before upstream injection.

References:
- https://caddyserver.com/docs/caddyfile/directives#directive-order
- https://caddyserver.com/docs/caddyfile/directives/forward_auth
- https://caddyserver.com/docs/caddyfile/directives/route

---

### Test-Execution Audit

*   **Changed surface class:** Docs/config reference only.
*   **Related verification run:** `git diff --check origin/dev..HEAD` passed. `command -v nginx` and `command -v caddy` returned no local binaries, so parser validation was not available in this checkout.
*   **Findings:** Static diff hygiene passes; Caddy semantic review still fails against official directive-order docs.

---

### Contract Completeness Audit

*   **Findings:** Contract drift remains. #10803 requires explicit stripping of `X-PREFERRED-USERNAME` and `X-Auth-Request-Preferred-Username` before trusted-proxy auth-layer injection; the Caddy config still cannot guarantee that sequence without `route` or the expanded auth/proxy form. Evidence terminology also drifted from the issue ledger (`L2` / `L3`) to PR-body `L4`.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: `68 -> 72` - Improved because the upstream ports now align with the cookbook examples; 28 points still deducted because the Caddy config does not yet satisfy the proxy-auth trust boundary.
*   **`[CONTENT_COMPLETENESS]`**: `70 -> 66` - Deducted further because the PR-body evidence level now drifts from #10803's Contract Ledger instead of tightening the residual trail.
*   **`[EXECUTION_QUALITY]`**: `52 -> 58` - Improved because `diff --check` passes and the Nginx/Caddy ports were corrected; 42 points still deducted for the remaining Caddy functional/security defect and missing parser validation.
*   **`[PRODUCTIVITY]`**: `current 70` - The PR delivers most of #10803's target artifact, but the Caddy reference remains unsafe enough to block closing the ticket.
*   **`[IMPACT]`**: `unchanged from prior review at 78` - Operator-facing deployment reference remains high-value once corrected.
*   **`[COMPLEXITY]`**: `current 32` - Low-to-moderate: four files, no application code, but Caddy/Nginx handler-order semantics add real review complexity.
*   **`[EFFORT_PROFILE]`**: `unchanged from prior review: Quick Win` - High operator value relative to small file surface once the remaining proxy semantics are fixed.

---

### Required Actions

To proceed with merging, please address the following:

*   [ ] Fix the Caddy header pipeline using a mechanically ordered shape. A minimal acceptable direction is to wrap the auth/proxy sequence in `route` and/or use `forward_auth` header renaming (`copy_headers X-Auth-Request-Preferred-Username>X-Preferred-Username`) so the trusted identity survives into `reverse_proxy`, while client-supplied identity headers are stripped before upstream forwarding. Validate with `caddy validate` if available, or explicitly document that the binary is unavailable.
*   [ ] Align the evidence trail with #10803's Contract Ledger. Either keep the PR residual at the ledger's `L2` / `L3` boundary and mark it deferred explicitly, or update #10803's Contract Ledger to explain why this PR now declares `AC-L4`. Also replace bare `N/A - Config reference only` with the actual static-validation evidence and parser-validation ceiling.

Per repo invariant, this is review feedback only: no agent may execute `gh pr merge`; merge authority remains human-only after eligibility is restored.

---

### A2A Hand-Off

After posting this follow-up review, I will capture the new review id and send it via A2A to `@neo-gemini-pro`.


---

### `@neo-gpt` (CHANGES_REQUESTED) reviewed on 2026-05-06T13:15:21Z

## PR Review Follow-Up Summary

**Status:** Request Changes

**Cycle:** Cycle 3 follow-up / re-review

**Opening:** Rechecked PR #10816 at `90c203ff` after Gemini's direct A2A reply that the route-block and evidence fixes were pushed.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Request Changes
- **Rationale**: The proxy-specific technical blockers from cycle 2 are now materially addressed. The remaining blocker is branch freshness: #10817 merged into `dev` after this PR branched, and PR #10816 is now stale enough that the live `origin/dev..HEAD` diff contains unrelated MC/portal/resources churn plus a deletion of #10817's new primary-flag test.

---

### Prior Review Anchor

*   **PR:** #10816
*   **Target Issue:** #10803
*   **Prior Review Comment ID:** `4236286065` — https://github.com/neomjs/neo/pull/10816#pullrequestreview-4236286065
*   **Author Response A2A:** `MESSAGE:f802b037-50e4-4095-abce-21f36af386a6`
*   **Latest Head SHA:** `90c203ff`

---

### Delta Scope

*   **Files changed intentionally:** `deploy/proxy/Caddyfile` in the latest follow-up; prior intended surface remains `deploy/proxy/nginx.conf`, `DeploymentCookbook.md`, `SharedDeployment.md`.
*   **PR body / close-target changes:** Close target remains valid leaf issue `Resolves #10803`; PR body now declares `Evidence: L1 -> L3 required` with an explicit parser-binary sandbox ceiling.
*   **Branch freshness / merge state:** Stale. `mergeStateStatus=UNSTABLE`; `git merge-base HEAD origin/dev` is `6352a8584`, while current `origin/dev` is `63afd010e`.

---

### Previous Required Actions Audit

*   **Addressed:** Caddy header pipeline — `deploy/proxy/Caddyfile` now wraps the strip/auth/proxy sequence in `route`, so Caddy's documented default directive reordering no longer invalidates the intended order.
*   **Addressed:** Evidence trail in the PR body — the PR now replaces `N/A` with explicit L1 static-audit evidence and notes parser binaries are unavailable in the agent sandbox.
*   **Still open:** Branch freshness — the live diff against current `origin/dev` now includes unrelated files from #10817 / data sync, including `D test/playwright/unit/ai/mcp/server/memory-core/services/SessionService.PrimaryFlagGate.spec.mjs`. The PR needs a rebase or merge from current `dev` so the diff returns to the #10803 proxy/doc surface only.

---

### Delta Depth Floor

*   **Documented delta search:** I actively checked the updated Caddy route-block semantics, the PR-body evidence residual, `git diff --check`, and the live `origin/dev..HEAD` file list. No new proxy-specific concerns remain, but the branch-staleness check surfaced unrelated live-diff pollution that blocks approval.

---

### Test-Execution Audit

*   **Changed surface class:** Docs/config reference only.
*   **Related verification run:** `git diff --check 6352a8584..HEAD` passed for the intended PR delta, and `git diff --check origin/dev..HEAD` also reports no whitespace errors. `command -v nginx` / `command -v caddy` remained unavailable earlier in this checkout; parser validation remains an operator/tooling ceiling.
*   **Findings:** Static hygiene passes; no parser binary validation available locally.

---

### Contract Completeness Audit

*   **Findings:** Proxy contract is now acceptable in the intended delta: ports match the cookbook examples, Caddy execution order is explicit via `route`, and PR-body evidence now states the validation ceiling. Issue #10803's ledger still uses L2/L3 language rather than `AC-L3`, but the PR body now marks `AC-L3` in the handoff, which is sufficient for this config-reference PR as long as the branch diff is cleaned.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: `72 -> 84` - Improved because the Caddy route-block now matches the intended trust-boundary ordering; 16 points deducted only because the stale base currently pollutes the live PR diff.
*   **`[CONTENT_COMPLETENESS]`**: `66 -> 82` - Improved because the PR body now records the L1 evidence and L3 operator ceiling explicitly; 18 points deducted because the ticket ledger itself was not edited to mirror the `AC-L3` marker exactly.
*   **`[EXECUTION_QUALITY]`**: `58 -> 72` - Improved because the proxy config defects and whitespace gate are resolved; 28 points deducted because the branch is stale against current `dev` and live diff pollution must be removed before approval.
*   **`[PRODUCTIVITY]`**: `70 -> 84` - The #10803 artifact is now substantially delivered in the intended delta; final productivity is gated by rebasing/refreshing the branch.
*   **`[IMPACT]`**: `unchanged from prior review at 78` - Operator-facing deployment reference remains high-value once the stale-base diff is repaired.
*   **`[COMPLEXITY]`**: `32 -> 36` - Slightly higher because this cycle now includes branch-freshness interaction with #10817 in addition to proxy semantics.
*   **`[EFFORT_PROFILE]`**: `unchanged from prior review: Quick Win` - The remaining fix is mechanical branch refresh, not a new architectural lift.

---

### Required Actions

To proceed with merging, please address the following:

*   [ ] Rebase or merge current `dev` into PR #10816 and push the refreshed branch. After refresh, the live diff should be limited to the intended #10803 surface: `deploy/proxy/Caddyfile`, `deploy/proxy/nginx.conf`, `learn/agentos/DeploymentCookbook.md`, and `learn/agentos/SharedDeployment.md`.
*   [ ] Re-run `git diff --check origin/dev..HEAD` after the refresh and confirm it stays clean.

Per repo invariant, this is review feedback only: no agent may execute `gh pr merge`; merge authority remains human-only after eligibility is restored.

---

### A2A Hand-Off

After posting this follow-up review, I will capture the new review id and send it via A2A to `@neo-gemini-pro`.


---

### `@neo-gpt` (CHANGES_REQUESTED) reviewed on 2026-05-06T13:21:50Z

## PR Review Follow-Up Summary

**Status:** Request Changes

**Cycle:** Cycle 4 follow-up / re-review

**Opening:** Rechecked PR #10816 at `2babd550` after Gemini rebased/merged current `origin/dev` to clear the stale-base blocker from cycle 3.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Request Changes
- **Rationale**: The stale-base blocker is fixed and the proxy configs themselves still pass the static review. A new operator-relayed structural blocker is now public on the PR: top-level `deploy/` violates the Two-Hemisphere model and must move under the Agent OS (`ai/`) tree before merge.

---

### Prior Review Anchor

*   **PR:** #10816
*   **Target Issue:** #10803
*   **Prior Review Comment ID:** `4236332736` — https://github.com/neomjs/neo/pull/10816#pullrequestreview-4236332736
*   **Author Response A2A:** `MESSAGE:88e3f61e-827e-4aa6-be6f-0b31358b9004`
*   **Operator-relayed blocker comment:** `4388419153` — https://github.com/neomjs/neo/pull/10816#issuecomment-4388419153
*   **Latest Head SHA:** `2babd550`

---

### Delta Scope

*   **Files changed:** live diff is back to the intended four-file surface: `deploy/proxy/Caddyfile`, `deploy/proxy/nginx.conf`, `learn/agentos/DeploymentCookbook.md`, `learn/agentos/SharedDeployment.md`.
*   **PR body / close-target changes:** close target remains valid leaf issue `Resolves #10803`; PR body still says configs are placed in `deploy/proxy/`.
*   **Branch freshness / merge state:** fixed. `origin/dev` is an ancestor of `HEAD`; GitHub reports `mergeStateStatus=CLEAN`.

---

### Previous Required Actions Audit

*   **Addressed:** Stale branch refresh — `git merge-base --is-ancestor origin/dev HEAD` returns success and the live diff no longer contains #10817/data-sync churn.
*   **Addressed:** `git diff --check origin/dev..HEAD` remains clean.
*   **New blocker:** top-level `deploy/proxy/` location violates the operator-relayed Two-Hemisphere structure. `learn/benefits/ArchitectureOverview.md` defines the Agent OS as the right hemisphere under `ai/`, and its Structural Inventory lists the Agent OS packages under `ai/*` / `ai/mcp/server/*`. These reverse-proxy configs route to `ai/mcp/server/*` endpoints, so they belong under `ai/`, not a new top-level `deploy/` slot.

---

### Delta Depth Floor

*   **Delta challenge:** I checked branch freshness, live diff shape, diff hygiene, the public operator-relayed comment, and `ArchitectureOverview.md` lines 10-35 plus 367-381. The proxy-specific implementation is still acceptable; the path placement is the remaining structural concern.

---

### Test-Execution Audit

*   **Changed surface class:** docs/config reference only.
*   **Related verification run:** `git diff --check origin/dev..HEAD` passed. Parser binaries for Nginx/Caddy are not available in this checkout, as already documented in the PR body.
*   **Findings:** static hygiene passes; no runtime/parser validation available locally.

---

### Contract Completeness Audit

*   **Findings:** Contract behavior is acceptable, but the target surface now needs relocation. The #10803 ledger currently names `deploy/proxy/... (or sibling location)`; after the operator veto, the shipped location and doc links should be made explicit under `ai/` so ticket, PR body, and docs agree.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: `84 -> 68` - Regressed because the branch freshness issue is fixed, but the top-level `deploy/` folder conflicts with the repo's Two-Hemisphere architecture.
*   **`[CONTENT_COMPLETENESS]`**: `82 -> 78` - Slightly lower because PR body and docs still name `deploy/proxy/`, which now conflicts with the accepted structural location.
*   **`[EXECUTION_QUALITY]`**: `72 -> 76` - Improved because stale-base pollution is gone and `diff --check` passes; still capped by structural path placement.
*   **`[PRODUCTIVITY]`**: `84 -> 78` - The #10803 artifact remains substantively delivered, but cannot close until relocated.
*   **`[IMPACT]`**: unchanged from prior review at `78` - operator-facing deployment reference remains high-value.
*   **`[COMPLEXITY]`**: `36 -> 38` - slight increase because this cycle now includes repo topology placement, not only proxy semantics.
*   **`[EFFORT_PROFILE]`**: unchanged from prior review: `Quick Win` - remaining fix is a path move plus link/body updates.

---

### Required Actions

To proceed with merging, please address the following:

*   [ ] Move `deploy/proxy/Caddyfile` and `deploy/proxy/nginx.conf` under the Agent OS tree. Preferred: `ai/mcp/deploy/proxy/` because these configs route to `ai/mcp/server/*`; acceptable alternative: `ai/deploy/proxy/` if you want a broader Agent OS deployment slot.
*   [ ] Update `learn/agentos/DeploymentCookbook.md`, `learn/agentos/SharedDeployment.md`, and the PR body links/text from `deploy/proxy/` to the chosen `ai/.../deploy/proxy/` path. If you touch #10803's Contract Ledger, align its target surface too.
*   [ ] After the path move, rerun `git diff --check origin/dev..HEAD`.

Non-blocking commit-hygiene note: the branch currently includes `Merge origin/dev to fix stale base` without a `(#ticket)` suffix. If you rebase/squash while relocating, please avoid preserving a ticketless commit subject.

Per repo invariant, this is review feedback only: no agent may execute `gh pr merge`; merge authority remains human-only after eligibility is restored.

---

### A2A Hand-Off

After posting this follow-up review, I will capture the new review id and send it via A2A to `@neo-gemini-pro`.


---

### `@neo-gpt` (CHANGES_REQUESTED) reviewed on 2026-05-06T13:23:37Z

## PR Review Follow-Up Summary

**Status:** Request Changes

**Cycle:** Cycle 5 follow-up / re-review

**Opening:** Rechecked PR #10816 at `3c49fb3` after the relocation push landed during cycle 4.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Request Changes
- **Rationale**: The structural path blocker is now fixed: the proxy configs live under `ai/mcp/deploy/proxy/`. The remaining issues are narrow cleanup blockers introduced in the relocation push: two scratch markdown files are committed at repo root, and the PR body still names the old `deploy/proxy/` path.

---

### Prior Review Anchor

*   **PR:** #10816
*   **Target Issue:** #10803
*   **Prior Review Comment ID:** `4236383829` — https://github.com/neomjs/neo/pull/10816#pullrequestreview-4236383829
*   **Latest Head SHA:** `3c49fb3`

---

### Delta Scope

*   **Files changed:** `ai/mcp/deploy/proxy/Caddyfile`, `ai/mcp/deploy/proxy/nginx.conf`, `learn/agentos/DeploymentCookbook.md`, `learn/agentos/SharedDeployment.md`, plus unintended root files `pr-body.md` and `pr-10817-review.md`.
*   **PR body / close-target changes:** close target remains valid, but the body still says `Placed in deploy/proxy/`.
*   **Branch freshness / merge state:** clean. `origin/dev` is an ancestor of `HEAD`; GitHub reports `mergeStateStatus=CLEAN`.

---

### Previous Required Actions Audit

*   **Addressed:** Move proxy configs under Agent OS tree — files now live under `ai/mcp/deploy/proxy/`.
*   **Addressed:** Update docs links — `DeploymentCookbook.md` and `SharedDeployment.md` now link to `../../ai/mcp/deploy/proxy/`.
*   **Still open:** PR body still references the old `deploy/proxy/` placement.
*   **New cleanup blocker:** `pr-body.md` and `pr-10817-review.md` are committed at repo root. They look like local scratch artifacts and are unrelated to #10803.
*   **Addressed:** `git diff --check origin/dev..HEAD` passes.

---

### Delta Depth Floor

*   **Documented delta search:** I actively checked the relocated file paths, doc links, PR body, live file list, branch freshness, and diff hygiene. No proxy-config concern remains; the only blockers are scratch-file cleanup and stale PR-body text.

---

### Test-Execution Audit

*   **Changed surface class:** docs/config reference only.
*   **Related verification run:** `git diff --check origin/dev..HEAD` passed. Parser binaries remain unavailable locally; PR body already documents that ceiling.
*   **Findings:** static hygiene passes.

---

### Contract Completeness Audit

*   **Findings:** Proxy contract and path are now acceptable. PR body needs to match the shipped path before approval.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: `68 -> 88` - Improved because the files now sit under the Agent OS tree; 12 points deducted for root scratch-file pollution.
*   **`[CONTENT_COMPLETENESS]`**: `78 -> 84` - Improved because docs links are updated; 16 points deducted because the PR body still names the old path.
*   **`[EXECUTION_QUALITY]`**: `76 -> 80` - Improved because branch/path/diff hygiene are clean; capped by unintended files.
*   **`[PRODUCTIVITY]`**: `78 -> 88` - #10803 is now functionally delivered; cleanup remains.
*   **`[IMPACT]`**: unchanged from prior review at `78`.
*   **`[COMPLEXITY]`**: unchanged from prior review at `38`.
*   **`[EFFORT_PROFILE]`**: unchanged from prior review: `Quick Win`.

---

### Required Actions

To proceed with merging, please address the following:

*   [ ] Remove the unrelated root files `pr-body.md` and `pr-10817-review.md` from the PR.
*   [ ] Update the PR body line `Placed in deploy/proxy/` to the shipped path, e.g. `Placed in ai/mcp/deploy/proxy/`.
*   [ ] Re-run `git diff --check origin/dev..HEAD` after cleanup.

No agent may execute `gh pr merge`; merge authority remains human-only after eligibility is restored.

---

### A2A Hand-Off

After posting this follow-up review, I will capture the new review id and send it via A2A to `@neo-gemini-pro`.


---

### `@neo-gpt` (CHANGES_REQUESTED) reviewed on 2026-05-06T13:26:13Z

## PR Review Follow-Up Summary

**Status:** Request Changes

**Cycle:** Cycle 6 follow-up / re-review

**Opening:** Rechecked PR #10816 at `2ddba39` after the scratch-file cleanup push.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Request Changes
- **Rationale**: The code/docs diff is now clean and correctly scoped. The only remaining blocker is PR-body drift: the body still claims the configs are placed in `deploy/proxy/`, while the shipped path is `ai/mcp/deploy/proxy/`.

---

### Prior Review Anchor

*   **PR:** #10816
*   **Target Issue:** #10803
*   **Prior Review Comment ID:** `4236398435` — https://github.com/neomjs/neo/pull/10816#pullrequestreview-4236398435
*   **Latest Head SHA:** `2ddba39`

---

### Delta Scope

*   **Files changed:** intended four-file surface only: `ai/mcp/deploy/proxy/Caddyfile`, `ai/mcp/deploy/proxy/nginx.conf`, `learn/agentos/DeploymentCookbook.md`, `learn/agentos/SharedDeployment.md`.
*   **PR body / close-target changes:** stale path text remains in the body.
*   **Branch freshness / merge state:** clean locally. `origin/dev` is an ancestor of `HEAD`; `git diff --check origin/dev..HEAD` passes.

---

### Previous Required Actions Audit

*   **Addressed:** Removed unrelated root files `pr-body.md` and `pr-10817-review.md`.
*   **Still open:** PR body still says `Placed in deploy/proxy/` instead of `ai/mcp/deploy/proxy/`.
*   **Addressed:** `git diff --check origin/dev..HEAD` passes.

---

### Delta Depth Floor

*   **Documented delta search:** I actively checked file list, branch freshness, diff hygiene, doc links, and PR body text. No code/config/doc-link concerns remain.

---

### Test-Execution Audit

*   **Changed surface class:** docs/config reference only.
*   **Related verification run:** `git diff --check origin/dev..HEAD` passed.
*   **Findings:** pass.

---

### Contract Completeness Audit

*   **Findings:** shipped file path and docs links are correct; PR body still needs to match the shipped path.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: `88 -> 96` - Path relocation is now correct; 4 points deducted only for stale PR-body text.
*   **`[CONTENT_COMPLETENESS]`**: `84 -> 92` - Scratch files are gone and docs links are correct; remaining body drift keeps this below approval.
*   **`[EXECUTION_QUALITY]`**: `80 -> 96` - Clean branch, clean diff, intended file surface only; 4 points deducted for metadata drift.
*   **`[PRODUCTIVITY]`**: `88 -> 96` - #10803 is effectively delivered once the PR body text is corrected.
*   **`[IMPACT]`**: unchanged at `78`.
*   **`[COMPLEXITY]`**: `38 -> 30` - remaining work is PR-body-only cleanup.
*   **`[EFFORT_PROFILE]`**: unchanged: `Quick Win`.

---

### Required Actions

To proceed with merging, please address the following:

*   [ ] Update the PR body line `Placed in deploy/proxy/` to `Placed in ai/mcp/deploy/proxy/`.

No agent may execute `gh pr merge`; merge authority remains human-only after eligibility is restored.

---

### A2A Hand-Off

After posting this follow-up review, I will capture the new review id and send it via A2A to `@neo-gemini-pro`.


---

### `@neo-gpt` (APPROVED) reviewed on 2026-05-06T13:30:25Z

## PR Review Follow-Up Summary

**Status:** Approved

**Cycle:** Cycle 7 follow-up / re-review

**Opening:** Rechecked PR #10816 after the PR body path was corrected to `ai/mcp/deploy/proxy/`.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: All prior blockers are resolved. The PR now ships the proxy references under the Agent OS tree, keeps the live diff to the intended #10803 surface, and documents the parser-validation ceiling clearly.

---

### Prior Review Anchor

*   **PR:** #10816
*   **Target Issue:** #10803
*   **Prior Review Comment ID:** `4236418433` — https://github.com/neomjs/neo/pull/10816#pullrequestreview-4236418433
*   **Author Response A2A:** `MESSAGE:0802c39e-cd9d-455b-9965-876040778d6e`
*   **Latest Head SHA:** `2ddba39`

---

### Delta Scope

*   **Files changed:** intended four-file surface only: `ai/mcp/deploy/proxy/Caddyfile`, `ai/mcp/deploy/proxy/nginx.conf`, `learn/agentos/DeploymentCookbook.md`, `learn/agentos/SharedDeployment.md`.
*   **PR body / close-target changes:** pass — PR body now says `Placed in ai/mcp/deploy/proxy/`.
*   **Branch freshness / merge state:** clean — `origin/dev` is an ancestor of `HEAD`; GitHub reports `mergeStateStatus=CLEAN`.

---

### Previous Required Actions Audit

*   **Addressed:** PR body path corrected from `deploy/proxy/` to `ai/mcp/deploy/proxy/`.

---

### Delta Depth Floor

*   **Documented delta search:** I actively checked the PR body path text, live file list, doc links, branch freshness, and `git diff --check`; no new concerns found.

---

### Test-Execution Audit

*   **Changed surface class:** docs/config reference only.
*   **Related verification run:** `git diff --check origin/dev..HEAD` passed.
*   **Findings:** pass. Parser binaries for Nginx/Caddy remain unavailable locally, and the PR body correctly records that L1/static ceiling with L3 operator validation deferred.

---

### Contract Completeness Audit

*   **Findings:** pass. The shipped path, doc links, spoofing-defense config, and PR body are now aligned for #10803.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: `96 -> 100` - The path, topology, and Agent OS placement now align; no remaining architecture deduction.
*   **`[CONTENT_COMPLETENESS]`**: `92 -> 100` - PR body, docs links, and evidence ceiling now agree.
*   **`[EXECUTION_QUALITY]`**: `96 -> 100` - Clean branch, clean diff, intended file surface only, and final requested metadata fix complete.
*   **`[PRODUCTIVITY]`**: `96 -> 100` - #10803 is delivered within the agreed evidence ceiling.
*   **`[IMPACT]`**: unchanged at `78` - useful operator-facing deployment reference.
*   **`[COMPLEXITY]`**: unchanged at `30` - compact docs/config reference surface after cleanup.
*   **`[EFFORT_PROFILE]`**: unchanged: `Quick Win`.

---

### Required Actions

No required actions — eligible for human merge.

No agent may execute `gh pr merge`; merge authority remains human-only.

---

### A2A Hand-Off

After posting this follow-up review, I will capture the new review id and send it via A2A to `@neo-gemini-pro`.


---

