dohertj2/mxaccessgw
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
c47b9d7b0258a9ce1ea4147ef316fa7ca4ed2419
mxaccessgw/docs/plans/2026-06-03-documentation-audit-implementation.md
T

17 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink