design doc: soften language, use neutral framing

Signed-off-by: Dawei Huang <daweihuang@microsoft.com>

Author: hdwhdw

doc/gnoi-native-grpc-design.md

@@ -2,23 +2,23 @@
 
 ## TL;DR
 
-`gnoi_shutdown_daemon` issues gNOI RPCs by shelling out to `docker exec gnmi gnoi_client`. This is fragile, opaque, and already causing silent failures. Replace with direct Python gRPC calls using vendored proto stubs.
+`gnoi_shutdown_daemon` issues gNOI RPCs by shelling out to `docker exec gnmi gnoi_client`. This introduces several layers of indirection that make failures hard to diagnose and completion detection unreliable. This document proposes replacing the subprocess path with direct Python gRPC calls using vendored proto stubs.
 
-## 1. Why This Pattern Is Bad
+## 1. Limitations of the Current Approach
 
-| Problem | Impact |
-|---------|--------|
-| Requires `gnmi` container running and healthy | DPU shutdown silently fails if gnmi is restarting |
-| Subprocess + Docker CLI overhead per RPC | Extra process creation, Docker round-trip, stdout capture |
-| Output is unstructured text with a header line | Any format change in `gnoi_client` breaks parsing |
-| gRPC status codes are lost | Caller only sees `rc != 0` — no code, no details |
-| Errors are Go `panic()` stack traces on stderr | Production diagnosis requires SSH + manual docker exec |
-| `suppress_stderr=True` discards those panics | Error output goes to `/dev/null`, logs say only "command failed" |
-| String matching for completion detection | `"reboot complete" in out_s.lower()` doesn't match actual output (see §2) |
-| Tight coupling to CLI flag interface | `-module System -rpc Reboot -jsonin '{...}'` is a serialization layer we don't need |
-| Security surface | Shell-out through Docker CLI is wider than a direct gRPC socket |
+| Observation | Consequence |
+|-------------|-------------|
+| Requires `gnmi` container running and healthy | DPU shutdown depends on an unrelated container's availability |
+| Subprocess + Docker CLI overhead per RPC | Extra process creation, Docker round-trip, stdout capture on each call |
+| Output is unstructured text with a header line | Parsing is coupled to `gnoi_client`'s print format, which has no stability guarantee |
+| gRPC status codes are not propagated | Caller only sees `rc != 0` — no status code, no error details |
+| Errors surface as Go `panic()` stack traces on stderr | Diagnosing RPC failures requires SSH + manual docker exec |
+| `suppress_stderr=True` on the Reboot call | Panic output is discarded; logs show only "command failed" |
+| Completion check uses string matching | `"reboot complete" in out_s.lower()` does not match actual output format (see §2) |
+| Tight coupling to CLI flag interface | `-module System -rpc Reboot -jsonin '{...}'` adds a serialization layer between caller and protobuf |
+| Broader privilege surface | Shell-out through Docker CLI vs. a direct gRPC socket |
 
-## 2. Already Broken: RebootStatus Parsing
+## 2. Existing Issue: RebootStatus Completion Detection
 
 The poll loop checks:
 
@@ -34,7 +34,7 @@ System RebootStatus
 {"active":false,"status":{"status":"STATUS_SUCCESS","message":"..."}}
 ```
 
-`"reboot complete"` never appears → poll **always times out** regardless of DPU state.
+`"reboot complete"` does not appear in this output → the poll always exhausts its timeout regardless of DPU state.
 
 ## 3. Proposed Change