docs(sisyphus): record sconet-pipeline plan and verification trail

Persist orchestration artifacts, including plan definition, progress state, decisions, issues, and learnings gathered during delegated execution and QA gates. This preserves implementation rationale and auditability without coupling documentation snapshots to runtime logic commits.
2026-02-27 09:59:26 +08:00
parent d6fd6c03e6
commit 3496a1beb7
7 changed files with 2279 additions and 0 deletions
@@ -0,0 +1,24 @@
+# Learnings: NATS Port Dynamic Allocation Fix
+
+## Problem
+- Hardcoded `NATS_PORT = 4222` caused test failures when port 4222 was occupied by system services
+- F4 flagged this as scope-fidelity drift
+
+## Solution
+- Added `_find_open_port()` helper using `socket.socket().bind(("127.0.0.1", 0))` to find available port
+- Updated `nats_server` fixture to yield `(bool, int)` tuple instead of just bool
+- Updated `_start_nats_container(port: int)` to accept dynamic port parameter
+- Wired dynamic port through all test methods using `nats_url = f"nats://127.0.0.1:{port}"`
+
+## Key Implementation Details
+1. Port discovery happens in fixture before container start
+2. Same port used for Docker `-p {port}:{port}` mapping and NATS URL
+3. Fixture returns `(False, 0)` when Docker/server unavailable to preserve skip behavior
+4. Cleanup via `_stop_nats_container()` preserved in `finally` block
+
+## Verification Results
+- `pytest tests/demo/test_nats.py -q`: 9 passed, 2 skipped (Docker unavailable in CI)
+- `basedpyright tests/demo/test_nats.py`: 0 errors, 1 warning (reportAny on socket.getsockname)
+
+## Files Modified
+- `tests/demo/test_nats.py` only (as required)