docs(arch-networking): minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh - #484

docs/specs/03-spec-networking/architecture.md (2)

177-177: 💤 Low value

Reword repeated "New" sentence openers for prose clarity.

Static analysis flagged three instances of successive sentences beginning with "New" (lines 177, 201–202), which slightly impacts readability:

• Line 177: "New net/ module tree:"
• Line 201: "New subcommand group mesh:"
• Line 202: "New subcommand ssh-forward:"

Consider varying the phrasing (e.g., "Introduces," "Adds," "The new") to improve flow.

✨ Proposed rewording

 ### `crates/minimal2/src/`
 
-New subcommand group `mesh`: `join`, `leave`, `status` (Unit 4).
-New subcommand `ssh-forward` (Unit 4).
-New subcommand `session policy` (Unit 2).
+Adds subcommand group `mesh`: `join`, `leave`, `status` (Unit 4).
+Introduces subcommand `ssh-forward` (Unit 4).
+Provides subcommand `session policy` (Unit 2).

(Or similar variation to reduce consecutive "New" openers.)

Also applies to: 201-202

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/architecture.md` at line 177, The documentation
file contains three consecutive sentences that begin with the word "New" (at
lines 177, 201, and 202), which reduces prose clarity. To fix this, reword these
sentence openers to vary the phrasing: change "New `net/` module tree:" on line
177, "New subcommand group `mesh`:" on line 201, and "New subcommand
`ssh-forward`:" on line 202 to use alternative phrasings such as "Introduces,"
"Adds," "The new," or other variations that improve the flow and readability of
the document.

Source: Linters/SAST tools

---

238-244: Note implementation dependency risk on spec-minvmd-networking-gvproxy (#404).

The knowledge gaps section (lines 238–244) identifies spec-minvmd-networking-gvproxy (#404) as foundational ("its NetworkMode enum, spawn_gvproxy, and check_network_policy stub are all re-usable") but also notes that "implementation has not landed yet" and the issue is still in sdd:triage.

This creates a sequencing risk: if #404's implementation diverges from the assumptions stated in this spec (e.g., gvproxy API surface, IP allocation strategy, lifecycle ownership), this spec may require revision before Unit 1 implementation begins.

Recommendation: Add a sequencing note in the assumption ledger or preamble clarifying that Unit 1 implementation should not begin until #404's implementation is landed and validated against the assumptions stated here.

Would you like me to add an explicit dependency tracking note to the spec's preamble or assumption ledger?

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/architecture.md` around lines 238 - 244, Add a
sequencing note to the spec's preamble or assumption ledger section (before or
near the knowledge gaps section around lines 238-244) that explicitly documents
the implementation dependency on issue `#404` (spec-minvmd-networking-gvproxy).
The note should clearly state that Unit 1 implementation must not commence until
`#404`'s implementation is landed and the actual implementation is validated
against the assumptions stated in this spec regarding the NetworkMode enum,
spawn_gvproxy function, and check_network_policy stub interfaces. This will make
the sequencing risk explicit and prevent downstream work from proceeding on
assumptions that may diverge from the eventual implementation.