Joseph Doherty
102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
# 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.
|