docs: add documentation-audit implementation plan (24 tasks, 13-cluster fan-out)

This commit is contained in:
Joseph Doherty
2026-06-03 14:00:47 -04:00
parent 327493f077
commit c47b9d7b02
2 changed files with 285 additions and 0 deletions
@@ -0,0 +1,255 @@
# 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 (113) — 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 113:
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 113** (disjoint fragment outputs, read-only on disjoint doc sets).
### Task 1: Verify Architecture cluster
**Classification:** small · **Est:** ~5 min · **Parallelizable with:** Tasks 213
**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,313
**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 12,413
**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 13,513
**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 14,613
**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 15,713
**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 16,813
**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 17,913
**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 18,1013
**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 19,1113
**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 110,1213
**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 111,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 112
**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 112) 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 113)
**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 (1622) 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 1622)
**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 (1622) — 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 1622** (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:** 1722 · **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,1822 · **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:** 1617,1922 · **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:** 1618,2022 · **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:** 1619,2122 · **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:** 1620,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:** 1621 · **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 1622)
**Files:**
- Modify: `MxAccessGateway-doc-audit.md` (mark each finding resolved/deferred)
- Read: all docs edited in Tasks 1522
**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 113 all at once; then 14; then 15; then 1622 all at once; then 23.
- **Worker/x86 build is not required** — verification is read-only against source. No Windows host needed for this plan.
@@ -0,0 +1,30 @@
{
"planPath": "docs/plans/2026-06-03-documentation-audit-implementation.md",
"tasks": [
{"id": 24, "subject": "Task 0: Scaffold audit workspace", "status": "pending"},
{"id": 25, "subject": "Task 1: Verify Architecture cluster", "status": "pending", "blockedBy": [24]},
{"id": 26, "subject": "Task 2: Verify Worker cluster", "status": "pending", "blockedBy": [24]},
{"id": 27, "subject": "Task 3: Verify Sessions/runtime cluster", "status": "pending", "blockedBy": [24]},
{"id": 28, "subject": "Task 4: Verify Auth cluster (high-drift)", "status": "pending", "blockedBy": [24]},
{"id": 29, "subject": "Task 5: Verify Dashboard cluster (high-drift)", "status": "pending", "blockedBy": [24]},
{"id": 30, "subject": "Task 6: Verify Config cluster", "status": "pending", "blockedBy": [24]},
{"id": 31, "subject": "Task 7: Verify Contracts/gRPC cluster", "status": "pending", "blockedBy": [24]},
{"id": 32, "subject": "Task 8: Verify Galaxy Repository cluster", "status": "pending", "blockedBy": [24]},
{"id": 33, "subject": "Task 9: Verify Alarms cluster", "status": "pending", "blockedBy": [24]},
{"id": 34, "subject": "Task 10: Verify Testing cluster", "status": "pending", "blockedBy": [24]},
{"id": 35, "subject": "Task 11: Verify Clients cluster", "status": "pending", "blockedBy": [24]},
{"id": 36, "subject": "Task 12: Verify Style-guides cluster (flag-only)", "status": "pending", "blockedBy": [24]},
{"id": 37, "subject": "Task 13: Verify Design-history/plans cluster (flag-only)", "status": "pending", "blockedBy": [24]},
{"id": 38, "subject": "Task 14: Synthesize findings report + dedup table", "status": "pending", "blockedBy": [25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37]},
{"id": 39, "subject": "Task 15: Apply global substitutions (mechanical)", "status": "pending", "blockedBy": [38]},
{"id": 40, "subject": "Task 16: Fix Architecture + Sessions", "status": "pending", "blockedBy": [39]},
{"id": 41, "subject": "Task 17: Fix Worker", "status": "pending", "blockedBy": [39]},
{"id": 42, "subject": "Task 18: Fix Auth (high-drift)", "status": "pending", "blockedBy": [39]},
{"id": 43, "subject": "Task 19: Fix Dashboard (high-drift)", "status": "pending", "blockedBy": [39]},
{"id": 44, "subject": "Task 20: Fix Config + Contracts + Galaxy + Alarms", "status": "pending", "blockedBy": [39]},
{"id": 45, "subject": "Task 21: Fix Clients", "status": "pending", "blockedBy": [39]},
{"id": 46, "subject": "Task 22: Fix Testing + Style-guides + history cross-refs", "status": "pending", "blockedBy": [39]},
{"id": 47, "subject": "Task 23: Re-verify changed claims + finalize report", "status": "pending", "blockedBy": [40, 41, 42, 43, 44, 45, 46]}
],
"lastUpdated": "2026-06-03"
}