Add Phase 0 + Phase 1 detailed implementation plans under docs/v2/implementation/ with a phase-gate model so the work can be verified for compliance to the v2 design as it lands. Three-gate structure per phase (entry / mid / exit) with explicit compliance-check categories: schema compliance (live DB introspected against config-db-schema.md DDL via xUnit), decision compliance (every decision number cited in the phase doc must have at least one code/test citation in the codebase, verified via git grep), visual compliance (Admin UI screenshots reviewed side-by-side against ScadaLink CentralUI's equivalent screens), behavioral compliance (per-phase end-to-end smoke test that always passes at exit, never "known broken fix later"), stability compliance (cross-cutting protections from driver-stability.md wired up and regression-tested for Tier C drivers), and documentation compliance (any deviation from v2 design docs reflected back as decision-log updates with explicit "supersedes" notes). Exit gate requires two-reviewer signoff and an exit-gate-{phase}.md record; silent deviation is the failure mode the gates exist to make impossible to ship. Phase 0 doc covers the mechanical LmxOpcUa → OtOpcUa rename with 9 tasks, 7 compliance checks, and a completion checklist that gates on baseline test count parity. Phase 1 doc covers the largest greenfield phase — 5 work streams (Core.Abstractions, Configuration project with EF Core schema + stored procs + LiteDB cache + generation-diff applier, Core with GenericDriverNodeManager rename + IAddressSpaceBuilder + driver isolation, Server with Microsoft.Extensions.Hosting replacing TopShelf + credential-bound bootstrap, Admin Blazor Server app mirroring ScadaLink CentralUI verbatim with LDAP cookie auth + draft/diff/publish workflow + UNS structure management + equipment CRUD + release-reservation and merge-equipment operator flows) — with task-level acceptance criteria, a 14-step end-to-end smoke test, and decision citation requirements for #1-125. New decisions #126-127 capture the gate model and per-phase doc structure. Cross-references added to plan.md Reference Documents section.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-17 11:25:09 -04:00
parent a59ad2e0c6
commit 592fa79e3c
4 changed files with 1062 additions and 0 deletions
--- a/docs/v2/implementation/overview.md
+++ b/docs/v2/implementation/overview.md
@@ -0,0 +1,180 @@
+# Implementation Plan Overview — OtOpcUa v2
+
+> **Status**: DRAFT — defines the gate structure, compliance check approach, and deliverable conventions used across all phase implementation plans (`phase-0-*.md`, `phase-1-*.md`, etc.).
+>
+> **Branch**: `v2`
+> **Created**: 2026-04-17
+
+## Purpose
+
+Each phase of the v2 build (`plan.md` §6 Migration Strategy) gets a dedicated detailed implementation doc in this folder. This overview defines the structure those docs follow so reviewers can verify compliance with the v2 design without re-reading every artifact.
+
+## Phase Gate Structure
+
+Every phase has **three gates** the work must pass through:
+
+```
+        ┌──────────┐       ┌──────────┐       ┌──────────┐
+START ──┤ ENTRY    │── do ──┤ MID      │── verify ──┤ EXIT     │── PHASE COMPLETE
+        │ GATE     │  work  │ GATE     │  artifacts │ GATE     │
+        └──────────┘        └──────────┘            └──────────┘
+```
+
+### Entry gate
+
+**Purpose**: ensures the phase starts with a known-good state and all prerequisites met. Prevents starting work on top of broken foundations.
+
+**Checked before any phase work begins**:
+- Prior phase has cleared its **exit gate** (or this is Phase 0)
+- Working tree is clean on the appropriate branch
+- All baseline tests for the prior phase still pass
+- Any external dependencies the phase needs are confirmed available
+- Implementation lead has read the phase doc and the relevant sections of `plan.md`, `config-db-schema.md`, `driver-specs.md`, `driver-stability.md`, `admin-ui.md`
+
+**Evidence captured**: a short markdown file `entry-gate-{phase}.md` recording the date, signoff, baseline test pass, and any deviations noted.
+
+### Mid gate
+
+**Purpose**: course-correct partway through the phase. Catches drift before it compounds. Optional for phases ≤ 2 weeks; required for longer phases.
+
+**Checked at the midpoint**:
+- Are the highest-risk deliverables landing on schedule?
+- Have any new design questions surfaced that the v2 docs don't answer? If so, escalate to plan revision before continuing.
+- Are tests being written alongside code, or accumulating as a backlog?
+- Has any decision (`plan.md` decision log) been silently violated by the implementation? If so, either revise the implementation or revise the decision (with explicit "supersedes" entry).
+
+**Evidence captured**: short status update appended to the phase doc.
+
+### Exit gate
+
+**Purpose**: ensures the phase actually achieved what the v2 design specified, not just "the code compiles". This is where compliance verification happens.
+
+**Checked before the phase is declared complete**:
+- All **acceptance criteria** for every task in the phase doc are met (each criterion has explicit evidence)
+- All **compliance checks** (see below) pass
+- All **completion checklist** items are ticked, with links to the verifying artifact (test, screenshot, log line, etc.)
+- Phase commit history is clean (no half-merged WIP, no skipped hooks)
+- Documentation updates merged: any change in approach during the phase is reflected back in the v2 design docs (`plan.md` decision log gets new entries; `config-db-schema.md` updated if schema differed from spec; etc.)
+- Adversarial review run on the phase output (`/codex:adversarial-review` or equivalent) — findings closed or explicitly deferred with rationale
+- Implementation lead **and** one other reviewer sign off
+
+**Evidence captured**: `exit-gate-{phase}.md` recording all of the above with links and signatures.
+
+## Compliance Check Categories
+
+Phase exit gates run compliance checks across these axes. Each phase doc enumerates the specific checks for that phase under "Compliance Checks".
+
+### 1. Schema compliance (Phase 1+)
+
+For phases that touch the central config DB:
+- Run EF Core migrations against a clean SQL Server instance
+- Diff the resulting schema against the DDL in `config-db-schema.md`:
+  - Table list matches
+  - Column types and nullability match
+  - Indexes (regular + unique + filtered) match
+  - CHECK constraints match
+  - Foreign keys match
+  - Stored procedures present and signatures match
+- Any drift = blocking. Either fix the migration or update the schema doc with explicit reasoning, then re-run.
+
+### 2. Decision compliance
+
+For each decision number cited in the phase doc (`#XX` references to `plan.md` decision log):
+- Locate the artifact (code module, test, configuration file) that demonstrates the decision is honored
+- Add a code comment or test name that cites the decision number
+- Phase exit gate uses a script (or grep) to verify every cited decision has at least one citation in the codebase
+
+This makes the decision log a **load-bearing reference**, not a historical record.
+
+### 3. Visual compliance (Admin UI phases)
+
+For phases that touch the Admin UI:
+- Side-by-side screenshots of equivalent ScadaLink CentralUI screens vs the new OtOpcUa Admin screens
+- Login page, sidebar, dashboard, generic forms — must visually match per `admin-ui.md` §"Visual Design — Direct Parity with ScadaLink"
+- Reviewer signoff: "could the same operator move between apps without noticing?"
+
+### 4. Behavioral compliance (end-to-end smoke tests)
+
+For each phase, an integration test exercises the new capability end-to-end:
+- Phase 0: existing v1 IntegrationTests pass under the renamed projects
+- Phase 1: create a cluster → publish a generation → node fetches the generation → roll back → fetch again
+- Phase 2: v1 IntegrationTests parity suite passes against the v2 Galaxy.Host (per decision #56)
+- Phase 3+: per-driver smoke test against the simulator
+
+Smoke tests are **always green at exit**, never "known broken, fix later".
+
+### 5. Stability compliance (Phase 2+ for Tier C drivers)
+
+For phases that introduce Tier C drivers (Galaxy in Phase 2, FOCAS in Phase 5):
+- All `Driver Stability & Isolation` cross-cutting protections from `driver-stability.md` §"Cross-Cutting Protections" are wired up:
+  - SafeHandle wrappers exist for every native handle
+  - Memory watchdog runs and triggers recycle on threshold breach (testable via FaultShim)
+  - Crash-loop circuit breaker fires after 3 crashes / 5 min (testable via stub-injected crash)
+  - Heartbeat between proxy and host functions; missed heartbeats trigger respawn
+  - Post-mortem MMF survives a hard process kill and the supervisor reads it on respawn
+- Each protection has a regression test in the driver's test suite
+
+### 6. Documentation compliance
+
+For every phase:
+- Any deviation from the v2 design docs (`plan.md`, `config-db-schema.md`, `admin-ui.md`, `driver-specs.md`, `driver-stability.md`, `test-data-sources.md`) is reflected back in the docs
+- New decisions added to the decision log with rationale
+- Old decisions superseded explicitly (not silently)
+- Cross-references between docs stay current
+
+## Deliverable Types
+
+Each phase produces a defined set of deliverables. The phase doc enumerates which deliverables apply.
+
+| Type | Format | Purpose |
+|------|--------|---------|
+| **Code** | Source files committed to a feature branch, merged to `v2` after exit gate | The implementation itself |
+| **Tests** | xUnit unit + integration tests; per-phase smoke tests | Behavioral evidence |
+| **Migrations** | EF Core migrations under `Configuration/Migrations/` | Schema delta |
+| **Decision-log entries** | New rows appended to `plan.md` decision table | Architectural choices made during the phase |
+| **Doc updates** | Edits to existing v2 docs | Keep design and implementation aligned |
+| **Gate records** | `entry-gate-{phase}.md`, `exit-gate-{phase}.md` in this folder | Audit trail of gate clearance |
+| **Compliance script** | Per-phase shell or PowerShell script that runs the compliance checks | Repeatable verification |
+| **Adversarial review** | `/codex:adversarial-review` output on the phase diff | Independent challenge |
+
+## Branch and PR Conventions
+
+| Branch | Purpose |
+|--------|---------|
+| `v2` | Long-running design + implementation branch. All phase work merges here. |
+| `v2/phase-{N}-{slug}` | Per-phase feature branch (e.g. `v2/phase-0-rename`) |
+| `v2/phase-{N}-{slug}-{subtask}` | Per-subtask branches when the phase is large enough to warrant them |
+
+Each phase merges to `v2` via PR after the exit gate clears. PRs include:
+- Link to the phase implementation doc
+- Link to the exit-gate record
+- Compliance-script output
+- Adversarial-review output
+- Reviewer signoffs
+
+The `master` branch stays at v1 production state until all phases are complete and a separate v2 release decision is made.
+
+## What Counts as "Following the Plan"
+
+The implementation **follows the plan** when, at every phase exit gate:
+
+1. Every task listed in the phase doc has been done OR explicitly deferred with rationale
+2. Every compliance check has a passing artifact OR an explicit deviation note signed off by the reviewer
+3. The codebase contains traceable references to every decision number the phase implements
+4. The v2 design docs are updated to reflect any approach changes
+5. The smoke test for the phase passes
+6. Two people have signed off — implementation lead + one other reviewer
+
+The implementation **deviates from the plan** when any of those conditions fails. Deviations are not failures; they are signals to update the plan or revise the implementation. The unrecoverable failure mode is **silent deviation** — code that doesn't match the plan, with no decision-log update explaining why. The exit gate's compliance checks exist specifically to make silent deviation impossible to ship.
+
+## Phase Implementation Docs
+
+| Phase | Doc | Status |
+|-------|-----|--------|
+| 0 | [`phase-0-rename-and-net10.md`](phase-0-rename-and-net10.md) | DRAFT |
+| 1 | [`phase-1-configuration-and-admin-scaffold.md`](phase-1-configuration-and-admin-scaffold.md) | DRAFT |
+| 2 | (Phase 2: Galaxy parity refactor — TBD) | NOT STARTED |
+| 3 | (Phase 3: Modbus TCP driver — TBD) | NOT STARTED |
+| 4 | (Phase 4: PLC drivers AB CIP / AB Legacy / S7 / TwinCAT — TBD) | NOT STARTED |
+| 5 | (Phase 5: Specialty drivers FOCAS / OPC UA Client — TBD) | NOT STARTED |
+| 6+ | (Phases 6–8: tier 1/2/3 consumer cutover — separate planning track per corrections doc C5) | NOT SCOPED |