suaveplan/openspec/changes/complete-network-plugins/tasks.md

Tasks — complete-network-plugins

Every checkbox MUST reflect work actually done in this change. Retroactive ticking is forbidden (AGENTS.md §13 step 6.7).

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Pre-flight

• 1.1 Re-read openspec/AGENTS.md §§0c, 13, 14
• 1.2 Re-read CLAUDE.md "Critical" rules 9, 10, 11
• 1.3 Confirm bare-throw inventory: grep -rnE "throw new (Error|TypeError|RangeError|SyntaxError)\(" packages/network/network-plugin-*/src/ --include="*.ts" | grep -v test returns the 17 sites in design.md §1
• 1.4 Confirm README malformation inventory: for f in packages/network/*/README.md; do n=$(grep -c "begin:auto-docs" "$f"); [ "$n" -gt 1 ] && echo "$n $f"; done | wc -l returns 43

2. Part A — error-handling migration

2.A.1 network-plugin-protocol

• 2.A.1.1 No new code needed — reuse NETWORK_PROTO_CODES.DESERIALIZATION_FAILED
• 2.A.1.2 src/decoder/decoder.ts:14 — replace bare throw with NetworkProtoError (see design §1)
• 2.A.1.3 Update src/decoder/decoder.md API Reference + Implementation Notes
• 2.A.1.4 Add assertion to src/decoder/decoder.spec-conformance.test.ts pinning instanceof NetworkProtoError + code === "NET_PROTO.DESERIALIZATION_FAILED" + context.reason === "incomplete-message"
• 2.A.1.5 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-protocol green
• 2.A.1.6 bunx turbo test:coverage --filter=@suaveplan/network-plugin-protocol 100/100/100/100

2.A.2 network-plugin-topology

• 2.A.2.1 Add INVALID_LATENCY_CONFIG to NETWORK_TOPO_CODES
• 2.A.2.2 Extend src/error-codes.spec-conformance.test.ts to pin the new code
• 2.A.2.3 src/latency/latency-assigner.ts:57 — replace bare throw with NetworkTopoError
• 2.A.2.4 src/latency/latency-assigner.ts:68 — replace bare throw with NetworkTopoError
• 2.A.2.5 Update src/latency/latency-assigner.md API Reference + Implementation Notes (document new code)
• 2.A.2.6 Update src/error-codes.md to document INVALID_LATENCY_CONFIG
• 2.A.2.7 Add assertions to src/latency/latency-assigner.spec-conformance.test.ts (create file if missing) pinning typed throws
• 2.A.2.8 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-topology green
• 2.A.2.9 bunx turbo test:coverage --filter=@suaveplan/network-plugin-topology 100/100/100/100

2.A.3 network-plugin-state

• 2.A.3.1 Add BLOOM_LENGTH_MISMATCH to NETWORK_STATE_CODES
• 2.A.3.2 Extend src/error-codes.spec-conformance.test.ts to pin the new code
• 2.A.3.3 src/bloom/bloom-filter-comparator.ts:56 — replace bare throw with NetworkStateError
• 2.A.3.4 Update src/bloom/bloom-filter-comparator.md API Reference + Implementation Notes
• 2.A.3.5 Update src/error-codes.md
• 2.A.3.6 Add assertion to existing *.spec-conformance.test.ts for the bloom comparator
• 2.A.3.7 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-state green
• 2.A.3.8 bunx turbo test:coverage --filter=@suaveplan/network-plugin-state 100/100/100/100

2.A.4 network-plugin-intra-relay

• 2.A.4.1 Add HYSTERESIS_CONFIG_INVALID and RATE_LIMIT_CONFIG_INVALID to NETWORK_INTRA_RELAY_CODES
• 2.A.4.2 Extend src/error-codes.spec-conformance.test.ts to pin both new codes
• 2.A.4.3 src/monitor/relay-performance-monitor.ts:51 — replace bare throw with NetworkIntraRelayError(HYSTERESIS_CONFIG_INVALID)
• 2.A.4.4 src/security/relay-security-manager.ts:57 — replace bare throw new RangeError with NetworkIntraRelayError(RATE_LIMIT_CONFIG_INVALID) (newly found)
• 2.A.4.5 src/security/relay-security-manager.ts:62 — replace bare throw new RangeError with NetworkIntraRelayError(RATE_LIMIT_CONFIG_INVALID) (newly found)
• 2.A.4.6 Update src/monitor/relay-performance-monitor.md and src/security/relay-security-manager.md
• 2.A.4.7 Update src/error-codes.md
• 2.A.4.8 Add assertions to src/monitor/*.spec-conformance.test.ts and src/security/*.spec-conformance.test.ts pinning typed throws + codes + context
• 2.A.4.9 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-intra-relay green
• 2.A.4.10 bunx turbo test:coverage --filter=@suaveplan/network-plugin-intra-relay 100/100/100/100

2.A.5 network-plugin-monitor

• 2.A.5.1 Add DASHBOARD_ROW_INVALID, BANDWIDTH_MONITOR_CONFIG_INVALID, DEGRADATION_CONFIG_INVALID to NETWORK_MON_CODES
• 2.A.5.2 Extend src/error-codes.spec-conformance.test.ts to pin all three new codes
• 2.A.5.3 src/grafana/dashboard-generator.ts:139 — replace bare throw with NetworkMonError(DASHBOARD_ROW_INVALID)
• 2.A.5.4 src/quality/bandwidth-monitor.ts:49 — replace bare throw new RangeError with NetworkMonError(BANDWIDTH_MONITOR_CONFIG_INVALID) (newly found)
• 2.A.5.5 src/quality/bandwidth-monitor.ts:53 — replace bare throw new RangeError with NetworkMonError(BANDWIDTH_MONITOR_CONFIG_INVALID) (newly found)
• 2.A.5.6 src/quality/degradation-manager.ts:50 — replace bare throw new RangeError with NetworkMonError(DEGRADATION_CONFIG_INVALID) (newly found)
• 2.A.5.7 src/quality/degradation-manager.ts:54 — replace bare throw new RangeError with NetworkMonError(DEGRADATION_CONFIG_INVALID) (newly found)
• 2.A.5.8 Update sibling .md files for all three touched modules
• 2.A.5.9 Update src/error-codes.md
• 2.A.5.10 Add assertions to src/grafana/*.spec-conformance.test.ts and src/quality/*.spec-conformance.test.ts pinning typed throws + codes + context
• 2.A.5.11 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-monitor green
• 2.A.5.12 bunx turbo test:coverage --filter=@suaveplan/network-plugin-monitor 100/100/100/100

2.A.6 Family-wide post-A scan

• 2.A.6.1 grep -rnE "throw new (Error|TypeError|RangeError|SyntaxError)\(" packages/network/network-plugin-*/src/ --include="*.ts" | grep -v test returns exactly zero lines
• 2.A.6.2 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-{protocol,topology,state,intra-relay,monitor} exits 0 for each

3. Part B — spec authoring

• 3.1 Confirm openspec/specs/network-plugin-{protocol,topology,state,intra-relay,monitor,auth,circuit-breaker,migration,partition,qos}/spec.md do NOT exist (per AGENTS.md §0c, openspec/specs/ is off-limits until archival)
• 3.2 Draft specs/network-plugin-protocol/spec.md (already shipped in this change)
• 3.3 Draft specs/network-plugin-topology/spec.md
• 3.4 Draft specs/network-plugin-state/spec.md
• 3.5 Draft specs/network-plugin-intra-relay/spec.md
• 3.6 Draft specs/network-plugin-monitor/spec.md
• 3.7 Draft specs/network-plugin-auth/spec.md
• 3.8 Draft specs/network-plugin-circuit-breaker/spec.md
• 3.9 Draft specs/network-plugin-migration/spec.md
• 3.10 Draft specs/network-plugin-partition/spec.md
• 3.11 Draft specs/network-plugin-qos/spec.md
• 3.12 Every ### Requirement has at least one #### Scenario and exactly one **Verified by:** line
• 3.13 bunx openspec validate complete-network-plugins --strict returns 0
• 3.14 Parity-vs-intent audit per plugin: walk every export in src/index.ts and confirm the spec delta names a requirement covering it (zero gaps)

4. Part C — README regeneration

• 4.1 Patch scripts/generate-package-module-tree.ts — convert replaceMarkedSection to a fixpoint loop that strips nested markers before re-injecting (see design §3)
• 4.2 Add scripts/generate-package-module-tree.test.ts pinning the double-run-idempotent invariant + the nested-marker collapse invariant
• 4.3 Run bun scripts/generate-package-module-tree.ts once to repair every malformed README
• 4.4 Verify: for f in packages/network/*/README.md; do n=$(grep -c "begin:auto-docs" "$f"); [ "$n" -eq 1 ] || echo "BAD: $f ($n)"; done returns zero lines
• 4.5 Verify a second run is byte-identical: cp packages/network/network-plugin-auth/README.md /tmp/auth.before && bun scripts/generate-package-module-tree.ts && diff /tmp/auth.before packages/network/network-plugin-auth/README.md returns no diff
• 4.6 Manually spot-check packages/network/network-plugin-auth/README.md renders cleanly (no _(no submodules)_ artifacts, no dangling markers)
• 4.7 Family-wide check across non-network packages: for f in packages/*/*/README.md; do n=$(grep -c "begin:auto-docs" "$f"); [ "$n" -gt 1 ] && echo "$n $f"; done — fix any stragglers in the same change

5. Part D — cross-cutting hygiene confirmation (per design §4)

• 5.1 for p in packages/network/network-plugin-*/; do for f in $(find "$p/src" -name "*.ts" ! -name "*.test.ts" ! -name "*.spec.ts" ! -name "*.types.ts" ! -name "index.ts" ! -name "*.spec-conformance.test.ts"); do md="${f%.ts}.md"; [ -f "$md" ] || echo "MISSING: $md"; done; done returns zero lines
• 5.2 for p in packages/network/network-plugin-*/; do [ -f "$p/README.md" ] || echo "MISSING: $p/README.md"; done returns zero lines
• 5.3 grep -rnE "from ['\"](vitest|bun:test)['\"]" packages/network/network-plugin-*/src/ --include="*.ts" returns zero lines (rule 11)
• 5.4 grep -rn "biome-ignore" packages/network/network-plugin-*/src/ --include="*.ts" reviewed — every hit justified or removed (rule 9)
• 5.5 grep -rn "export \*" packages/network/network-plugin-*/src/*/index.ts returns zero lines (rule 10)
• 5.6 bun scripts/lint/check-test-runner-imports.ts exits 0

6. Pre-archive 5-gate triple (AGENTS.md §13) — repeat per plugin

For each of: protocol, topology, state, intra-relay, monitor, auth, circuit-breaker, migration, partition, qos:

• 6..1 bun run check — Biome 0 errors / 0 warnings / 0 info
• 6..2 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-<pkg> green
• 6..3 bunx turbo test:coverage --filter=@suaveplan/network-plugin-<pkg> 100/100/100/100
• 6..4 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-<pkg> exit 0
• 6..5 bunx turbo build --filter=@suaveplan/network-plugin-<pkg> green

7. Dependent sweep (§13 step 10)

• 7.1 bunx turbo test --filter=...@suaveplan/network-plugin-protocol --filter=...@suaveplan/network-plugin-topology --filter=...@suaveplan/network-plugin-state --filter=...@suaveplan/network-plugin-intra-relay --filter=...@suaveplan/network-plugin-monitor green
• 7.2 bunx turbo test --filter=@suaveplan/network --filter=@suaveplan/network-testing --filter=@suaveplan/network-bootstrap green

8. Root-doc refresh (§13b)

• 8.1 bun scripts/folder-reorg/generate-manifest.ts — refresh MANIFEST.md
• 8.2 bun scripts/generate-missing.ts — refresh MISSING.yml
• 8.3 bunx markdownlint-cli2 --fix — apply across touched files
• 8.4 bunx markdownlint-cli2 second pass — exit 0
• 8.5 git status — only intentional changes remain

9. Archive (§14)

• 9.1 Fold each of the 10 specs/network-plugin-<name>/spec.md deltas into the canonical openspec/specs/network-plugin-<name>/spec.md (the canonical files do not exist yet — first fold creates them)
• 9.2 Move openspec/changes/complete-network-plugins/ → openspec/archive/2026-MM-DD-complete-network-plugins/
• 9.3 Update STATUS.md rows for the 10 plugins to reflect the new spec coverage