lmxopcua/archreview/plans/00-INDEX.md

Arch-Review Remediation Plans — Index

📊 Remediation status → STATUS.md. As of 2026-07-08: 2 of 4 Criticals done (03/S1 split-brain resolver; 02/U2+U3 VT timeout+ALC) + both CLAUDE.md doc-drifts fixed. Each Critical is on its own fix/archreview-crit* branch off master; plans live only on docs/archreview-plans-and-drift-fixes.

Design + implementation plans for every finding in the 2026-07-08 architecture review (archreview/*.md, review commit 9cad9ed0). Each plan verifies every finding against the current tree, then gives root cause → design (with alternatives) → concrete file-level steps → tests → effort/risk.

Plan documents

#	Plan	Findings	Verification
01	Core & composition	21	all confirmed, 0 stale
02	Scripting & alarms	30	all confirmed, 0 stale
03	Server & runtime	28	all confirmed (U1 = stale doc only)
04	AdminUI	20	all confirmed (C-3/C-4 good, no action)
05	Protocol drivers	37 + 1 positive	all confirmed, 0 stale
06	Gateway integrations	28 (23 actionable)	all confirmed (U-1 = stale doc)
07	Client, tooling & engineering	26	all confirmed, 0 stale

Total: ~190 findings planned. Zero were stale-because-already-fixed; the only "stale" items are two documentation drifts (CLAUDE.md Known Limitation 2) both flagged for correction.

The 4 Criticals (fix first)

#	Critical	Plan	Fix shape
1	Split-brain resolver never activated → no hard-crash failover	03 S1	ClusterOptions.SplitBrainResolver = KeepOldestOption + hard-kill failover test
2	Production VT script timeout is dead code → one loop wedges the actor	02 U2 (+U3)	Route through TimedScriptEvaluator + CompiledScriptCache
3	S7 has no reconnect path → PLC reboot kills the driver	05 STAB-1	IS7PlcFactory seam + lazy EnsureConnectedAsync
4	TwinCAT ADS subs orphaned after reconnect → silent data stop	05 STAB-2	Store replayable registration intent, replay on client swap

Cross-cutting guardrails (from OVERALL themes, span multiple plans)

• Theme #1 built-but-never-wired — the recurring failure mode. Guardrails proposed across plans: reflection-exhaustive DeferredAddressSpaceSink forwarding test (03 U2, sequenced before the surgical-add work), wiring the OTOPCUA0001 analyzer repo-wide (07 C-1), a startup log line proving SBR is active (03 S1), and wiring/removing the dormant historian health surface (06 S-6).
• Theme #2/#6 fixes don't flow to shared templates — Part B of plan 05: PollGroupEngine v2 (backoff + onError + delete the S7 fork), shared strict ReadEnum/ReadBool, ConnectionBackoff primitive, ResolveHost-via-resolver; plus TagConfigIntent.Parse in Commons (01 C-1) killing the 4-project byte-parity duplication.
• Theme #3 optimistic success — failure-visibility fixes: AddressSpaceApplyOutcome failure field (01 S-1), Galaxy write fail-closed (06 S-1), primary-gate default-deny on unknown role (03 S4).
• Theme #4 verification gap — CI to all unit suites + fail-on-skip (07 S-1/S-2), fault-injection tier (hard-kill / drop-PLC), the missing bUnit substitute = reflection/policy guards (04 C-1).
• Theme #5 doc drift — fix CLAUDE.md Known Limitation 2 + scadaproj index (03 U1 / 06 U-1), ScriptAnalysis policy doc, Client.CLI docs (07 U-3).
• Theme #7 repo hygiene — git rm -r lib/ AVEVA DLLs, untrack planning files, delete Wonderware husks (07 U-4/U-5/U-6).

Suggested execution order

Front-loaded per the OVERALL prioritized action list — items 1–6 eliminate every Critical plus the two systemic guards (analyzer + CI) that stop the built-but-never-wired pattern recurring:

1. Criticals — 03 S1, 02 U2+U3, 05 STAB-1, 05 STAB-2 (each with its missing test)
2. Systemic guards — 07 C-1 (analyzer) + 07 S-1/S-2 (CI to all suites, fail-on-skip); 03 U2 (Deferred-sink forwarding test)
3. Silent-corruption Highs — 05 STAB-4/5 (AbCip lock, FOCAS caches), 05 Modbus timeout-fatal classification
4. Failure-visibility Highs — 01 S-1, 06 S-1, 03 S4
5. AdminUI authz — 04 C-1 (ConfigEditor policy + reflection guard)
6. Perf — 03 P1 (surgical pure-adds, after 03 U2 guard)
7. Consolidation + hygiene + docs — 01 C-1, 05 Part B, 07 U-4/U-5, doc fixes

Open maintainer decision

• Prune vs. keep the dormant machinery (01 U-2 / 02 U-1): the callerless Tier-C recycle machinery + IDriverSupervisor, and the ~2.4k-line Core.VirtualTags engine that production bypasses. Plans recommend retiring both after the live paths are hardened (02 U2/U3 first), but the delete-vs-keep call is the maintainer's.