# 📋 Cross-Code Review Report — Job 924d3546

- **Job ID**: 924d3546
- **Reviewer**: cline (herdr:canary-projects-multi-agent-mux-creator-cline)
- **Review Target**: Working-tree changes to `PRIVATE_SERVER.md` (Rev.2), new `implementation_plan.md`, and `tests/test_deploy_freshness.py` (+4 guard tests)
- **Base Commit**: `a9934ad` (docs(messaging): add NATS vs MQTT feasibility report...)
- **Review Date**: 2026-08-20
- **Task Goal**: Update PRIVATE_SERVER.md to document nats-server versatility/multi-project advantages; establish phased milestones and 4-track roadmap in implementation_plan.md

---

## 1. Review Scope

### 1.1 Changed Files (git status)
| File | Status | Size Change |
|---|---|---|
| `PRIVATE_SERVER.md` | Modified (M) | 190 → 327 lines (+137 net, 221 ins / 42 del) |
| `implementation_plan.md` | New (??) | 167 lines |
| `tests/test_deploy_freshness.py` | Modified (M) | +90 lines (4 new test functions) |
| `.agents/reports/.../report-95c9fcaf.md` | New (??) | Previous review report (out of scope) |

### 1.2 Review Dimensions
1. **Lint/Formatting**: Markdown structure, code-fence syntax, table integrity
2. **Operational Correctness (동작성)**: Config validity, CLI flag accuracy, env var names
3. **Codebase Accuracy (유실/정합성)**: Line references, function names, file paths
4. **Cross-Document Consistency**: PRIVATE_SERVER.md ↔ implementation_plan.md ↔ IMPROVEMENTS.md ↔ NATS_REPORT.md
5. **Test Soundness**: New guard tests (G-D1~G-D4) correctness and regression safety

---

## 2. Codebase Accuracy Verification

### 2.1 Critical Config Fix — `-m 1883` → `mqtt { port: 1883 }`
| Claim | Verification | Result |
|---|---|---|
| `-m` flag sets HTTP monitoring port, NOT MQTT | nats-server docs: `-m` = `--http_port` | ✅ Correct fix |
| MQTT requires `mqtt { port: 1883 }` config block | nats-server MQTT adapter requires config-file activation | ✅ Correct |
| `-c nats.conf` is the correct launch method | nats-server `-c` = `--config` flag | ✅ Correct |

**Note (PRIVATE_SERVER.md §4.1)**: Added explicit `[!NOTE]` callout explaining the `-m` vs MQTT distinction. This directly addresses the E-1 finding from the prior review (job ae8933f4). ✅ Resolved.

### 2.2 Environment Variable Names — `MQTT_*` vs deprecated `MAM_MQTT_*`
| Documented Var | `broker_config_from_env()` (mqtt_common.py:225-234) | Match |
|---|---|:---:|
| `MQTT_BROKER` | `os.environ.get("MQTT_BROKER", "broker.hivemq.com")` | ✅ |
| `MQTT_PORT` | `_env_int("MQTT_PORT", 1883)` | ✅ |
| `MQTT_TLS` | `_env_bool("MQTT_TLS", False)` | ✅ |
| `MQTT_USERNAME` | `os.environ.get("MQTT_USERNAME")` | ✅ |
| `MQTT_PASSWORD` | `os.environ.get("MQTT_PASSWORD")` | ✅ |
| `MQTT_CA_CERTS` | `os.environ.get("MQTT_CA_CERTS")` | ✅ |
| `MQTT_CERTFILE` | `os.environ.get("MQTT_CERTFILE")` | ✅ |
| `MQTT_KEYFILE` | `os.environ.get("MQTT_KEYFILE")` | ✅ |

All 8 documented env vars match the actual `broker_config_from_env()` implementation exactly. The deprecated `MAM_MQTT_*` prefix has been removed from all active code blocks. ✅

### 2.3 Line References in implementation_plan.md
| Reference | Actual Location | Result |
|---|---|:---:|
| `multi-agent-mux-delegate-job:331-341` (sub_rc mapping) | Lines 328-341: `wait "$sub_pid" \|\| sub_rc=$?` + `if/elif/else` mapping `rc=0→completed, rc=1→error, else→timeout` | ✅ Exact |
| `reconcile.sh:237` (legacy global topic) | Line 237: `_c.subscribe("python/mqtt/jobs/+/events", qos=1)  # legacy fallback during transition` | ✅ Exact |
| `job_subscriber.py:233` (queue.Empty branch) | Actual `queue.Empty` at line **228** (5-line drift) | ⚠️ Minor |
| `registry.register_job()` auth_token (Track 2) | `registry.py` register function exists | ✅ |

**Finding M-1 (Minor)**: `implementation_plan.md` §3.2 references `job_subscriber.py:233` for the `queue.Empty` branch, but the actual `except queue.Empty:` is at line **228**. This is a 5-line drift. Since this is a forward-looking reference for Track 0 work (not yet implemented), the drift is cosmetic and will be re-validated when the code is actually modified. IMPROVEMENTS.md (committed) correctly uses the broader range `job_subscriber.py:172-251`. **Non-blocking.**

### 2.4 Test Count Evolution
| Claim | Verification | Result |
|---|---|:---:|
| Baseline: 276 tests (commit a9934ad) | `pytest --collect-only`: 280 total (276 + 4 new) | ✅ |
| M0 milestone: 276 → 280 | 4 new tests D-11~D-14 added to test_deploy_freshness.py | ✅ |
| M1 target: 280 → 290 | Forward-looking (Track 0 not yet implemented) | N/A |

---

## 3. Test Verification

### 3.1 New Guard Tests (G-D1 ~ G-D4)
| Test ID | Guard | Verification | Result |
|---|---|---|:---:|
| `test_d11_private_server_env_names_valid` | G-D1: Only valid `MQTT_*` vars in code blocks | Regex extracts `MQTT_[A-Z0-9_]+` from fenced blocks, checks against valid set | ✅ PASS |
| `test_d12_private_server_no_mam_mqtt_in_code_fences` | G-D2: No deprecated `MAM_MQTT_*` in code fences | Scans all code blocks for `MAM_MQTT_` prefix | ✅ PASS |
| `test_d13_private_server_nats_config_valid` | G-D3: nats config uses `mqtt {` not `-m 1883` | Asserts `-m 1883` absent, `mqtt {` present, `-c` present | ✅ PASS |
| `test_d14_private_server_cli_args_valid` | G-D4: CLI args match actual argparse parsers | Asserts no `register --job-id`, `status --job ` present | ✅ PASS |

**Test execution**: `pytest tests/test_deploy_freshness.py::test_d11...test_d14 -v` → **4 passed in 0.02s** ✅

### 3.2 Regression Safety
| Suite | Result |
|---|:---:|
| `test_deploy_freshness.py` (full file, 13 tests) | **13 passed in 13.00s** ✅ |
| `pytest --collect-only` (whole repo) | **280 tests collected** ✅ |

**Assessment**: The 4 new tests are pure documentation-content assertions (regex pattern matching on PRIVATE_SERVER.md code blocks). They introduce **zero side effects** — no fixtures mutated, no subprocess calls, no file writes. The existing 9 tests (D1-D10) in the same file are unaffected. No regression risk to the broader 276-test baseline. ✅

---

## 4. Cross-Document Consistency

### 4.1 PRIVATE_SERVER.md ↔ implementation_plan.md
| Consistency Item | PRIVATE_SERVER.md | implementation_plan.md | Match |
|---|---|---|:---:|
| Env var prefix | `MQTT_*` (§6) | `MQTT_*` (Track 3 table) | ✅ |
| nats-server launch | `nats-server -c nats.conf` (§4.1) | `nats-server -c nats.conf` (S-1 spike) | ✅ |
| Config block | `mqtt { port: 1883 }` + `jetstream { }` (§4.1) | References `nats.conf` config | ✅ |
| Phase ordering | Phase 1 (Track 0) → Phase 2 (broker) → Phase 3 (A-2) (§8) | M1 → M2 → M3 (§2) | ✅ |
| Cross-reference links | Links to `implementation_plan.md` (header) | Links to `PRIVATE_SERVER.md` (header + Track 3) | ✅ Bidirectional |
| Track 0 precedence | "방탄 아키텍처 원칙" — Track 0 first (§2) | "핵심 원칙" — Step 1→2→3 strict order (§3) | ✅ |

### 4.2 implementation_plan.md ↔ IMPROVEMENTS.md (committed a9934ad)
| Item | implementation_plan.md | IMPROVEMENTS.md | Match |
|---|---|---|:---:|
| B-14 description | `publish_event.py` early exit → 65min hang | P1-1: same description | ✅ |
| B-15 description | `job_subscriber.py` 120s delay + false-failure | P1-2: same description | ✅ |
| F-4 reference | `delegate-job:331-341` sub_rc mapping | Line 84: same reference | ✅ |
| Priority ordering | P1 (B-14/B-15) → P2 (O-5) → P3 (A-2) | P1-1, P1-2, P2-1, P3-1 | ✅ |

### 4.3 Track 3 Referenced Files — Existence Check
| Referenced File | Exists? |
|---|:---:|
| `MESSAGING.md` | ✅ |
| `IMPROVEMENTS.md` | ✅ |
| `VERSIONS.md` | ✅ |
| `deploy/install.sh` | ✅ |
| `.mam.env` (template) | Track 3 target (not yet created) |

All forward-referenced files in Track 3 exist in the repository. ✅

---

## 5. PRIVATE_SERVER.md Section 5 — Versatility Review

The new Section 5 ("하나의 서버로 여러 프로젝트 — nats-server 다능성") fulfills the task goal of documenting multi-project advantages:

| Subsection | Content | Accuracy |
|---|---|:---:|
| §5.1 Two Consumption Planes | ASCII diagram: Plane A (MQTT/paho) vs Plane B (NATS/WebSocket) | ✅ Sound architecture description |
| §5.2 Cross-Protocol Bridging | MQTT topic `/` → NATS subject `.` auto-translation | ✅ Accurate (nats-server MQTT bridge behavior) |
| §5.3 JetStream Event Replay | Opt-in stream on `python.mqtt.jobs.>` subject, `max_age`/`max_bytes` caveat | ✅ Correct + good capacity warning |
| §5.4 KV & Object Store | Built-in KV/Object, explicit non-goal (don't replace `.mam/jobs/*.json`) | ✅ Excellent guardrail |
| §5.5 Multi-tenant Accounts | MAM vs HOME account separation | ✅ Sound |

**Key design discipline**: §5.4 explicitly forbids replacing MAM's local registry with JetStream KV, preserving the `wait_for_job` fcntl/filesystem polling contract. This is a critical non-goal guardrail that prevents architectural drift. ✅

---

## 6. Findings

### 6.1 Minor (Non-blocking)

| ID | Severity | File | Description | Recommendation |
|---|---|---|---|---|
| **M-1** | Low | `implementation_plan.md` §3.2 | `job_subscriber.py:233` line reference for `queue.Empty` branch; actual line is **228** (5-line drift) | Update to `:228` or use range `:225-235` when Track 0 is implemented. Non-blocking — forward-looking reference. |
| **M-2** | Low | `implementation_plan.md` header | Version string `v1.0.0 (8c651798 / 28bb7340)` contains hash fragments not matching any commit in `git log` (file is untracked) | Use actual commit hash once committed, or remove placeholder hashes. Cosmetic only. |
| **M-3** | Low-Med | `PRIVATE_SERVER.md` §4.1 nats.conf | `store_dir: "~/.local/share/nats/data"` — tilde (`~`) may not be expanded by nats-server config parser (config files often require absolute paths) | The native binary section (§4.1 method B) creates the dir explicitly and uses the same path — if nats-server doesn't expand `~`, users hit a startup error. Consider documenting absolute path (`/home/user/.local/...`) or noting that nats-server v2.10+ does expand `~`. Docker path (`/data`) is correct. |
| **M-4** | Low | `PRIVATE_SERVER.md` §4.1 docker-compose.yml | `version: '3.8'` key is deprecated in Docker Compose v2+ (produces a warning, not an error) | Remove the `version:` line for Compose v2 compatibility. Non-blocking. |

### 6.2 No Issues Found (Verified Clean)

- **No `MAM_MQTT_*` leakage**: All deprecated env var references removed from active code blocks (G-D2 test enforces) ✅
- **No `-m 1883`残留**: Invalid MQTT flag completely removed (G-D3 test enforces) ✅
- **No broken cross-references**: All linked documents exist; bidirectional links between PRIVATE_SERVER.md and implementation_plan.md ✅
- **No test regression**: 13/13 deploy_freshness tests pass; 280 total collected ✅
- **No orphaned/dead content**: The diff cleanly replaces old config with corrected config; no leftover contradictory statements ✅
- **No scope creep**: Changes strictly address the task goal (versatility docs + roadmap); no unrelated files modified ✅

---

## 7. Operational Soundness Assessment

### 7.1 Docker Deployment (§4.1 Method A)
- ✅ `nats.conf` mounted read-only (`:ro`) — correct security posture
- ✅ Named volume `nats-data` for JetStream persistence — survives container restarts
- ✅ Port mappings include all 4 planes (1883 MQTT, 4222 NATS, 8222 HTTP, 8080 WebSocket)
- ✅ `--restart unless-stopped` for production resilience
- ⚠️ `version: '3.8'` deprecated (M-4)

### 7.2 Native Binary Deployment (§4.1 Method B)
- ✅ Uses user home directory (`~/.config/nats/`, `~/.local/share/nats/data`) — avoids macOS sealed APFS root issues
- ✅ `mkdir -p` without sudo — correct non-root approach
- ✅ Homebrew and Linux binary instructions both provided
- ✅ Heredoc config generation — reproducible
- ⚠️ Tilde expansion in `store_dir` (M-3)

### 7.3 Verification Procedure (§7, 4-Step)
- ✅ Step 1: HTTP monitoring endpoint check (`/varz`, `/jsz`) — correct nats-server monitoring API
- ✅ Step 2: Proper job registration → event publish → status cleanup flow (matches actual `registry.py`/`publish_event.py` CLI contracts)
- ✅ Step 3: IP assertion against `broker.hivemq.com` absence — directly validates A-2 security goal
- ✅ Step 4: pytest regression — correct (mock-based, broker-independent)
- ✅ Note correctly explains mock-based tests don't validate real network (honest scope statement)

---

## 8. implementation_plan.md Roadmap Soundness

### 8.1 Milestone Gating Logic
| Milestone | Gate Condition | Soundness |
|---|---|:---:|
| M0 | G-D1~G-D4 tests pass (276→280) | ✅ Achieved in this change set |
| M1 | G-1~G-10 guards + mutation FAIL (280→290) | ✅ Well-defined mutation testing criteria |
| M2 | S-3 Retained Terminal Event gate (mosquitto fallback) | ✅ Clear go/no-go decision point |
| M3 | Fingerprint topic verified before legacy removal (290→291) | ✅ Safe 3-step transition (no big-bang) |
| M4 | Full test suite 100% green | ✅ Standard completion gate |

### 8.2 Dependency Graph
The plan correctly identifies that Track 0 (fault-tolerance) is **broker-independent** and must precede Track 1 (nats-server spike). The rollback strategy (S-3 failure → switch `.mam.env` to mosquitto, 100% reversible) is sound and correctly notes Track 0 patches are permanent pure-gains. ✅

### 8.3 Guard Matrix Completeness (G-1~G-10)
The 10 guard definitions in §3.4 each have a clear mutation-detection criterion. The guards cover:
- Publish-side state sync (G-1~G-4): rc=2 + status sync + audit log + seq monotonicity
- Subscribe-side disk fallback (G-5~G-8): 3s exit + disk-fallback label + rc mapping + multi-job safety
- Infra rc=3 separation (G-9~G-10): broker-unavailable classification + no false-error propagation

This is a thorough, well-reasoned test strategy. ✅

---

## 9. Verdict Summary

### 9.1 Pass Criteria Evaluation
| Criterion | Status |
|---|:---:|
| Task goal fulfilled (PRIVATE_SERVER.md versatility docs) | ✅ Section 5 added with 5 subsections |
| Task goal fulfilled (implementation_plan.md roadmap) | ✅ 4 tracks, 5 milestones, 10 guards, 9 spike criteria |
| All codebase accuracy claims verified | ✅ 10/10 (1 minor line-drift M-1) |
| All new tests pass | ✅ 4/4 G-D1~G-D4 |
| No test regression | ✅ 13/13 deploy_freshness, 280 collected |
| Cross-document consistency | ✅ PRIVATE_SERVER ↔ plan ↔ IMPROVEMENTS aligned |
| No critical/high-severity findings | ✅ Only 4 low-severity minor findings |
| No design-level rework needed | ✅ Architecture sound, no ESCALATE warranted |

### 9.2 Findings Severity Distribution
| Severity | Count |
|---|:---:|
| Critical | 0 |
| High | 0 |
| Medium | 0 |
| Low | 4 (M-1 through M-4) |

All findings are cosmetic/minor and do not affect correctness, safety, or the ability to proceed to Track 0 implementation. None require design changes or replanning.

---

## 10. Reviewer Notes

- **Editor filesystem caveat**: This report was written via shell `cat >>` heredocs (not the `editor` tool) due to the known ephemeral editor filesystem issue where writes are invisible to shell commands. File persistence verified via `wc -l` and final-line check.
- **Full test suite**: The complete 280-test suite was not run end-to-end (exceeds the 30s shell timeout due to subprocess-heavy integration tests). However: (a) `pytest --collect-only` confirms 280 tests collect cleanly, (b) the full `test_deploy_freshness.py` file (13 tests including all 4 new + 9 existing) passes in 13s, and (c) the changes are documentation-only + pure-assertion tests with zero side effects on existing test fixtures.
- **Baseline integrity**: The `a9934ad` commit (prior review job 95c9fcaf verified 276 baseline) is preserved; this change set adds 4 tests cleanly on top.

---

[VERDICT: PASS]