From c47b9d7b0258a9ce1ea4147ef316fa7ca4ed2419 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 3 Jun 2026 14:00:47 -0400 Subject: [PATCH] docs: add documentation-audit implementation plan (24 tasks, 13-cluster fan-out) --- ...6-03-documentation-audit-implementation.md | 255 ++++++++++++++++++ ...ntation-audit-implementation.md.tasks.json | 30 +++ 2 files changed, 285 insertions(+) create mode 100644 docs/plans/2026-06-03-documentation-audit-implementation.md create mode 100644 docs/plans/2026-06-03-documentation-audit-implementation.md.tasks.json diff --git a/docs/plans/2026-06-03-documentation-audit-implementation.md b/docs/plans/2026-06-03-documentation-audit-implementation.md new file mode 100644 index 0000000..3c38534 --- /dev/null +++ b/docs/plans/2026-06-03-documentation-audit-implementation.md @@ -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-.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: +LINES: +CLAIM: +CLAIM_TYPE: path | config-key | rpc/proto | port | term | behavior-rule | command | cross-ref | version +VERDICT: accurate | stale | wrong | unverifiable | gap +EVIDENCE: +CODE_AREA: +SEVERITY: high | medium | low +PROPOSED_FIX: +``` + +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 — `. + +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.`. + +### 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.`. + +### 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//` 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.`. + +### 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 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. diff --git a/docs/plans/2026-06-03-documentation-audit-implementation.md.tasks.json b/docs/plans/2026-06-03-documentation-audit-implementation.md.tasks.json new file mode 100644 index 0000000..7fd210e --- /dev/null +++ b/docs/plans/2026-06-03-documentation-audit-implementation.md.tasks.json @@ -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" +}