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

# Documentation Audit Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans (or subagent-driven-development) to implement this plan task-by-task.

**Goal:** Audit every prose doc in the repo for accuracy and completeness against the current code/contracts, produce an evidence-backed findings report, then apply fixes.

**Architecture:** Two phases. **Verify** — 13 cluster verifier subagents read their docs + the relevant source and emit structured findings into per-cluster fragment files. **Fix** — a synthesis task aggregates fragments, dedups findings by `code_area` into a global-substitutions table and writes the report; a mechanical substitution pass applies repo-wide renames/path fixes; per-cluster fix tasks apply judgment edits; a final pass re-verifies changed claims. Prose only — never edit code.

**Tech Stack:** Markdown docs; C# (.NET 10 gateway / .NET Framework 4.8 x86 worker); protobuf contracts; 5 language clients (.NET, Go, Rust, Python, Java). Verification reads source under `src/` and `clients/`. No build required (prose), but fenced shell/build commands in docs are sanity-checked against real invocations.

**Design source:** `docs/plans/2026-06-03-documentation-audit-design.md`

**Branch:** Recommended `docs/prose-audit` off `main` (keeps this independent of the in-flight `docs/xml-doc-comments` PR). Decide at execution start; the executor must not work on `main`.

---

## Shared artifacts

- **Fragments dir:** `docs/audit/fragments/` — one Markdown fragment per cluster, `NN-<cluster>.md`. Tracked in git (evidence trail).
- **Report:** `MxAccessGateway-doc-audit.md` (repo root; not gitignored — only `*-docs-{issues,fixed,final}.md` are).
- **Findings schema** (every fragment entry, one block per claim, blocks separated by `---`):

```
DOC: <repo-relative doc path>
LINES: <line or range in the doc>
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
EVIDENCE: <source file:line that proves the verdict, or "none — feature absent">
CODE_AREA: <dedup tag, e.g. auth.roles, dashboard.theme, worker.frameproto>
SEVERITY: high | medium | low
PROPOSED_FIX: <replacement text, or "flag only">
```

Severity rule: `high` = misleads an integrator/operator (wrong port, wrong config key, wrong RPC, wrong auth behavior, broken build command); `medium` = stale-but-not-dangerous; `low` = cosmetic/typo/style.

Design-history docs (cluster 13) are point-in-time records: verify internal consistency and that no *living* doc cites them as current truth, but `PROPOSED_FIX` must be "flag only" for divergence-from-current-code — do **not** rewrite history to match code.

---

## Task 0: Scaffold audit workspace

**Classification:** trivial
**Estimated implement time:** ~2 min
**Parallelizable with:** none

**Files:**
- Create: `docs/audit/fragments/.gitkeep`
- Create: `docs/audit/README.md` (one paragraph: what this dir is, links to design + report)

**Steps:**
1. Confirm current branch is not `main`; if on `main`, create/switch to `docs/prose-audit`.
2. `mkdir -p docs/audit/fragments` and add `.gitkeep`.
3. Write `docs/audit/README.md` explaining the fragments are per-cluster audit evidence feeding `MxAccessGateway-doc-audit.md`, and link `docs/plans/2026-06-03-documentation-audit-design.md`.
4. Commit: `docs(audit): scaffold prose-audit workspace`.

**Acceptance:** `docs/audit/fragments/` exists and is tracked; not on `main`.

---

## Verifier tasks (1–13) — read-only, run in parallel

Each verifier task is **read-only analysis**. The subagent reads ONLY its assigned docs and the listed source, then writes its fragment file. It does not edit any doc or any code. Every finding must cite real `file:line` evidence; spot-check 3 citations before finishing. Use the findings schema above.

Common procedure for Tasks 1–13:
1. Read each assigned doc fully.
2. Extract every concrete, verifiable claim (paths, config keys, RPC/proto names, ports, role/term names, behavior rules, commands, cross-references, versions).
3. For each claim, locate the source of truth under the listed code area and assign a verdict + evidence + severity + proposed fix.
4. Also record `gap` entries: features/behaviors present in code but undocumented in the assigned docs.
5. Write all findings to the fragment file; commit `docs(audit): cluster NN findings — <name>`.

All verifier tasks are **Parallelizable with: Tasks 1–13** (disjoint fragment outputs, read-only on disjoint doc sets).

### Task 1: Verify Architecture cluster
**Classification:** small · **Est:** ~5 min · **Parallelizable with:** Tasks 2–13
**Files:** Create `docs/audit/fragments/01-architecture.md`
**Docs:** `gateway.md`, `docs/DesignDecisions.md`, `docs/GatewayProcessDesign.md`
**Verify against:** `src/` project layout, two-process model (`src/ZB.MOM.WW.MxGateway.{Server,Worker,Contracts}`), IPC pipe naming, STA model in `src/ZB.MOM.WW.MxGateway.Worker`.

### Task 2: Verify Worker cluster
**Classification:** small · **Est:** ~5 min · **Parallelizable with:** Tasks 1,3–13
**Files:** Create `docs/audit/fragments/02-worker.md`
**Docs:** `docs/WorkerBootstrap.md`, `docs/WorkerConversion.md`, `docs/WorkerFrameProtocol.md`, `docs/WorkerProcessLauncher.md`, `docs/WorkerSta.md`, `docs/MxAccessWorkerInstanceDesign.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Worker/**`, `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_worker.proto`.

### Task 3: Verify Sessions/runtime cluster
**Classification:** small · **Est:** ~3 min · **Parallelizable with:** Tasks 1–2,4–13
**Files:** Create `docs/audit/fragments/03-sessions.md`
**Docs:** `docs/Sessions.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Server/Sessions/**`, `.../Workers/**`.

### Task 4: Verify Auth cluster (high-drift)
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** Tasks 1–3,5–13
**Files:** Create `docs/audit/fragments/04-auth.md`
**Docs:** `docs/Authentication.md`, `docs/Authorization.md`, `glauth.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Server/Security/**`. Pay special attention to recent migration: API keys moved to `ZB.MOM.WW.Auth.ApiKeys`, role rename `Admin`→`Administrator`, LDAP base DN unified to `dc=zb,dc=local`, `ZbClaimTypes`/`ZbCookieDefaults`, scopes (`session`,`invoke`,`event`,`metadata`,`admin`), cookie name `__Host-MxGatewayDashboard`, SignalR hub token behavior. Tag these `auth.roles`, `auth.apikeys`, `auth.ldap`, `auth.cookie` for dedup.

### Task 5: Verify Dashboard cluster (high-drift)
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** Tasks 1–4,6–13
**Files:** Create `docs/audit/fragments/05-dashboard.md`
**Docs:** `docs/DashboardInterfaceDesign.md`, `docs/GatewayDashboardDesign.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Server/Dashboard/**`, `.../wwwroot/**`. Note recent migration to `ZB.MOM.WW.Theme` (ThemeShell/ThemeHead/ThemeScripts, StatusPill), pruned sidebar/login CSS, Blazor LoginCard. Confirm the "no UI component libraries (local Bootstrap only)" rule still matches reality. Tag `dashboard.theme`, `dashboard.login`.

### Task 6: Verify Config cluster
**Classification:** small · **Est:** ~5 min · **Parallelizable with:** Tasks 1–5,7–13
**Files:** Create `docs/audit/fragments/06-config.md`
**Docs:** `docs/GatewayConfiguration.md`, `docs/Diagnostics.md`, `docs/Metrics.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Server/Configuration/**` (`GatewayOptions`, `GatewayOptionsValidator`), `.../Diagnostics/**`, `.../Metrics/**`, `appsettings.json`. Check every `MxGateway:*` key, default, and validation rule. Tag `config.<key>`.

### Task 7: Verify Contracts/gRPC cluster
**Classification:** small · **Est:** ~5 min · **Parallelizable with:** Tasks 1–6,8–13
**Files:** Create `docs/audit/fragments/07-contracts.md`
**Docs:** `docs/Contracts.md`, `docs/Grpc.md`, `docs/ClientProtoGeneration.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Contracts/Protos/{mxaccess_gateway,galaxy_repository,mxaccess_worker}.proto`, `src/ZB.MOM.WW.MxGateway.Server/Grpc/**`. Confirm every RPC name, message, and service described matches the `.proto`. Tag `proto.<rpc>`.

### Task 8: Verify Galaxy Repository cluster
**Classification:** small · **Est:** ~3 min · **Parallelizable with:** Tasks 1–7,9–13
**Files:** Create `docs/audit/fragments/08-galaxy.md`
**Docs:** `docs/GalaxyRepository.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Server/Galaxy/**`, `galaxy_repository.proto`.

### Task 9: Verify Alarms cluster
**Classification:** small · **Est:** ~3 min · **Parallelizable with:** Tasks 1–8,10–13
**Files:** Create `docs/audit/fragments/09-alarms.md`
**Docs:** `docs/AlarmClientDiscovery.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.Server/Alarms/**`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/Alarm*.cs`.

### Task 10: Verify Testing cluster
**Classification:** small · **Est:** ~5 min · **Parallelizable with:** Tasks 1–9,11–13
**Files:** Create `docs/audit/fragments/10-testing.md`
**Docs:** `docs/GatewayTesting.md`, `docs/ClientBehaviorFixtures.md`, `docs/ParityFixtureMatrix.md`, `docs/CrossLanguageSmokeMatrix.md`, `docs/ToolchainLinks.md`
**Verify against:** `src/ZB.MOM.WW.MxGateway.{Tests,Worker.Tests,IntegrationTests}/**`, env-var gates (`MXGATEWAY_RUN_LIVE_*`), `LiveMxAccessFactAttribute`/`LiveLdapFactAttribute`, `scripts/run-client-e2e-tests.ps1`. Sanity-check every fenced command and tool version/path.

### Task 11: Verify Clients cluster
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** Tasks 1–10,12–13
**Files:** Create `docs/audit/fragments/11-clients.md`
**Docs:** `clients/{dotnet,go,java,python,rust}/README.md` + each `*ClientDesign.md`, `docs/ClientLibrariesDesign.md`, `docs/ClientPackaging.md`
**Verify against:** each `clients/<lang>/` source + build manifests (`*.csproj`/`go.mod`/`Cargo.toml`/`pyproject.toml`/`build.gradle`). Confirm install/build/test commands, package names, and proto-generation steps match reality. Tag `client.<lang>`.

### Task 12: Verify Style-guides cluster (normative — flag-only)
**Classification:** small · **Est:** ~3 min · **Parallelizable with:** Tasks 1–11,13
**Files:** Create `docs/audit/fragments/12-styleguides.md`
**Docs:** `StyleGuide.md`, `REVIEW-PROCESS.md`, `docs/style-guides/*.md`
**Verify against:** observed conventions in the corresponding source trees. These prescribe rather than describe — record only contradictions between a stated rule and actual pervasive practice; `PROPOSED_FIX` mostly "flag only".

### Task 13: Verify Design-history/plans cluster (records — flag-only)
**Classification:** small · **Est:** ~4 min · **Parallelizable with:** Tasks 1–12
**Files:** Create `docs/audit/fragments/13-history.md`
**Docs:** `docs/ImplementationPlan{Index,Gateway,Clients,MxAccessWorker}.md`, `docs/plans/*`
**Verify against:** check internal consistency and whether any *living* doc (clusters 1–12) cites these as current truth. Do NOT propose rewriting history to match code — `PROPOSED_FIX` is "flag only" except for genuinely broken internal cross-references.

---

## Task 14: Synthesize findings report + dedup table

**Classification:** standard
**Estimated implement time:** ~5 min
**Parallelizable with:** none (blocked by Tasks 1–13)

**Files:**
- Read: `docs/audit/fragments/*.md`
- Create: `MxAccessGateway-doc-audit.md`

**Steps:**
1. Read all 13 fragments.
2. Build the **summary**: counts by verdict, by severity, by cluster.
3. Build the **global-substitutions table**: group findings by `CODE_AREA` + normalized claim; any rename/moved-path/renamed-term that recurs becomes one row `old → new (applies to: doc list)`. This is the C-dedup output.
4. Append **per-doc findings** (all fragment blocks, grouped by doc, ordered high→low severity).
5. Add a short **fix plan** mapping each fix task (16–22) to the findings it must resolve.
6. Commit: `docs(audit): findings report + global-substitutions table`.

**Acceptance:** report exists with summary, substitutions table, and every fragment finding represented; high-severity findings listed first per doc.

---

## Task 15: Apply global substitutions (mechanical, repo-wide)

**Classification:** standard
**Estimated implement time:** ~4 min
**Parallelizable with:** none (blocked by Task 14; blocks 16–22)

**Files:** every doc named in the substitutions table (prose only — never code).

**Steps:**
1. For each substitutions row, apply the `old → new` replacement across the listed docs only.
2. Be precise — do not over-replace (e.g. don't rewrite a deliberately historical mention in cluster-13 docs; the table's "applies to" list excludes those).
3. After each row, grep the repo docs to confirm no unintended remaining/òver-broad matches.
4. Commit: `docs(audit): apply global term/path substitutions`.

**Acceptance:** every substitutions row applied to exactly its listed docs; `git diff` touches only `.md` files; spot-grep shows no stale term left in living docs.

---

## Fix tasks (16–22) — per-cluster judgment edits, run in parallel

Each fix task consumes the report's findings for its docs and applies each `PROPOSED_FIX` that is not "flag only". Honor `StyleGuide.md` (PascalCase filenames, present tense, explain *why* not *what*, no marketing language). Prose only. Do not re-apply global substitutions (Task 15 already did). All fix tasks are **Parallelizable with: Tasks 16–22** (disjoint doc sets) and **blocked by Task 15**.

Common procedure: read the report section for the cluster → apply each non-flag-only fix → re-read the edited doc to confirm coherence → commit `docs(audit): fix <cluster> findings`.

### Task 16: Fix Architecture + Sessions
**Classification:** small · **Est:** ~4 min · **Parallelizable with:** 17–22 · **Blocked by:** 15
**Files:** `gateway.md`, `docs/DesignDecisions.md`, `docs/GatewayProcessDesign.md`, `docs/Sessions.md`

### Task 17: Fix Worker
**Classification:** small · **Est:** ~4 min · **Parallelizable with:** 16,18–22 · **Blocked by:** 15
**Files:** `docs/Worker{Bootstrap,Conversion,FrameProtocol,ProcessLauncher,Sta}.md`, `docs/MxAccessWorkerInstanceDesign.md`

### Task 18: Fix Auth (high-drift)
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** 16–17,19–22 · **Blocked by:** 15
**Files:** `docs/Authentication.md`, `docs/Authorization.md`, `glauth.md`

### Task 19: Fix Dashboard (high-drift)
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** 16–18,20–22 · **Blocked by:** 15
**Files:** `docs/DashboardInterfaceDesign.md`, `docs/GatewayDashboardDesign.md`

### Task 20: Fix Config + Contracts/gRPC + Galaxy + Alarms
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** 16–19,21–22 · **Blocked by:** 15
**Files:** `docs/GatewayConfiguration.md`, `docs/Diagnostics.md`, `docs/Metrics.md`, `docs/Contracts.md`, `docs/Grpc.md`, `docs/ClientProtoGeneration.md`, `docs/GalaxyRepository.md`, `docs/AlarmClientDiscovery.md`

### Task 21: Fix Clients
**Classification:** standard · **Est:** ~5 min · **Parallelizable with:** 16–20,22 · **Blocked by:** 15
**Files:** `clients/{dotnet,go,java,python,rust}/README.md` + each `*ClientDesign.md`, `docs/ClientLibrariesDesign.md`, `docs/ClientPackaging.md`

### Task 22: Fix Testing + Style-guides + history cross-refs
**Classification:** small · **Est:** ~4 min · **Parallelizable with:** 16–21 · **Blocked by:** 15
**Files:** `docs/GatewayTesting.md`, `docs/ClientBehaviorFixtures.md`, `docs/ParityFixtureMatrix.md`, `docs/CrossLanguageSmokeMatrix.md`, `docs/ToolchainLinks.md`, `StyleGuide.md`, `REVIEW-PROCESS.md`, `docs/style-guides/*.md`, and only broken internal cross-refs in `docs/ImplementationPlan*.md` / `docs/plans/*` (no history rewrites).

---

## Task 23: Re-verify changed claims + finalize report

**Classification:** standard
**Estimated implement time:** ~5 min
**Parallelizable with:** none (blocked by Tasks 16–22)

**Files:**
- Modify: `MxAccessGateway-doc-audit.md` (mark each finding resolved/deferred)
- Read: all docs edited in Tasks 15–22

**Steps:**
1. For every `high`/`medium` finding that had a non-flag-only fix, re-check the edited prose against the same `EVIDENCE` source to confirm it is now accurate and no new inaccuracy was introduced.
2. Sanity-check every fenced shell/build command edited in this audit against the real invocation (compare to `CLAUDE.md` Build/Test/Run and each client README).
3. Update the report: each finding → `resolved` | `deferred (flag-only)` | `still-open` with a one-line note. Add a final tally.
4. Commit: `docs(audit): finalize report — resolution status`.

**Acceptance:** no `high`-severity finding left `still-open` without an explicit deferral note; report tally matches the fixes committed; `git diff --stat` across the branch shows only `.md` changes.

---

## Notes for the executor

- **Read-only verifiers must not edit docs or code.** If a verifier is tempted to fix, it records a `PROPOSED_FIX` instead.
- **Never touch source code.** This audit changes `.md` only. A `git diff --stat` containing any non-`.md` file is a defect.
- **Parallel dispatch:** Tasks 1–13 all at once; then 14; then 15; then 16–22 all at once; then 23.
- **Worker/x86 build is not required** — verification is read-only against source. No Windows host needed for this plan.