mxaccessgw/docs/plans/2026-06-03-documentation-audit-design.md

Documentation Audit Design

Date: 2026-06-03

Goal: Audit all prose documentation in the repository for accuracy and completeness against the current code/contracts, then apply fixes — producing both an evidence-backed findings report and corrected docs.

Decisions

• Deliverable: Findings report and applied fixes (reviewable commit).
• Scope: All prose docs — top-level (gateway.md, glauth.md, StyleGuide.md, REVIEW-PROCESS.md), docs/**, the 6 style guides, and all 10 client README + design docs (~55 files).
• Verification depth: Deep, claim-by-claim, against this repo's code and contracts only (not the external mxaccess / lmxopcua/gr reference projects).
• Approach: A + C dedup — per-subsystem verifier fan-out (A), with findings additionally keyed by code area so renamed terms / moved paths are fixed consistently everywhere at once (C).

Architecture

Two-phase pipeline:

• Phase 1 — Verify (fan-out). ~13 verifier subagents, one per subsystem cluster. Each reads its docs and the relevant source/contracts and returns a structured findings list.
• Phase 2 — Fix. Aggregate findings → dedup by code area into a global substitutions table → apply mechanical substitutions repo-wide, then per-cluster judgment fixes. Every fix cites the finding that justifies it.

No code changes; prose only. Source of truth is the repo's own code/contracts.

Cluster map (Phase 1 fan-out)

#	Cluster	Docs	Verified against
1	Architecture	gateway.md, DesignDecisions.md, GatewayProcessDesign.md	top-level src layout, two-process model
2	Worker	Worker{Bootstrap,Conversion,FrameProtocol,ProcessLauncher,Sta}.md, MxAccessWorkerInstanceDesign.md	…MxGateway.Worker
3	Sessions/runtime	Sessions.md	Server sessions/workers
4	Auth (high drift)	Authentication.md, Authorization.md, glauth.md	Security/Authentication, ZB.MOM.WW.Auth migration
5	Dashboard (high drift)	DashboardInterfaceDesign.md, GatewayDashboardDesign.md	dashboard + ZB.MOM.WW.Theme migration
6	Config	GatewayConfiguration.md, Diagnostics.md, Metrics.md	GatewayOptions(Validator), appsettings
7	Contracts/gRPC	Contracts.md, Grpc.md, ClientProtoGeneration.md	.proto + generated
8	Galaxy repo	GalaxyRepository.md	GR SQL browse RPCs
9	Alarms	AlarmClientDiscovery.md	alarm worker/server code
10	Testing	GatewayTesting.md, ClientBehaviorFixtures.md, ParityFixtureMatrix.md, CrossLanguageSmokeMatrix.md, ToolchainLinks.md	test projects, harness, fixtures
11	Clients ×5	each clients/<lang>/README.md + <Lang>ClientDesign.md, ClientLibrariesDesign.md, ClientPackaging.md	each client's source
12	Style guides (normative)	StyleGuide.md, REVIEW-PROCESS.md, docs/style-guides/*	spot-check vs observed conventions; flag-only
13	Design-history/plans	ImplementationPlan*.md, docs/plans/*	point-in-time records — verify internal consistency + that no living doc cites them as current truth; do not rewrite to match code

Findings schema

Each verifier returns, per claim:

• doc_file, doc_lines
• claim — the concrete assertion (verbatim or tight paraphrase)
• claim_type — path | config-key | rpc/proto | port | term | behavior-rule | command | cross-ref | version
• verdict — accurate | stale | wrong | unverifiable | gap (missing doc for an existing feature)
• code_evidence — file:line proving the verdict
• code_area — dedup tag (e.g. auth.roles, dashboard.theme)
• severity — high (misleads integrator/operator) | medium | low
• proposed_fix — replacement text, or "flag only"

Dedup layer (the C ingredient)

Aggregate all findings; group by code_area + normalized claim. Renamed terms and moved paths collapse into one global substitutions table (old → new) applied once repo-wide. Doc-specific judgment fixes stay per-doc.

Report

MxAccessGateway-doc-audit.md (matching the existing *-docs-*.md report convention): summary counts by verdict/severity/cluster, the global substitutions table, then per-doc findings with evidence and proposed fixes.

Fix pass & verification

1. Apply global substitutions first (mechanical, repo-wide).
2. Apply per-cluster judgment fixes — each citing a finding ID, honoring StyleGuide.md (PascalCase filenames, present tense, explain why not what, no marketing language).
3. Re-verify changed claims (lighter spot pass) to confirm resolution and no new drift.
4. Sanity-check any fenced shell/build commands in docs against current invocations.

Out of scope (YAGNI)

• Rewriting design-history docs to match current code (they are records).
• XML doc-comments (handled in a prior pass; the *-docs-*.md analyzer is clean).
• External mxaccess / lmxopcua/gr reference projects.

Branch note

Current branch is docs/xml-doc-comments (a separate PR in flight). The audit fixes are best kept on their own branch (docs/prose-audit off main) so the two reviews stay independent.