📋 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
- Lint/Formatting: Markdown structure, code-fence syntax, table integrity
- Operational Correctness (동작성): Config validity, CLI flag accuracy, env var names
- Codebase Accuracy (유실/정합성): Line references, function names, file paths
- Cross-Document Consistency: PRIVATE_SERVER.md ↔ implementation_plan.md ↔ IMPROVEMENTS.md ↔ NATS_REPORT.md
- 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]
