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.<pkg>.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info
- [ ] 6.<pkg>.2 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-<pkg>` green
- [ ] 6.<pkg>.3 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-<pkg>` 100/100/100/100
- [ ] 6.<pkg>.4 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-<pkg>` exit 0
- [ ] 6.<pkg>.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