Phase plan — waterutility.org

QA refresh (uplift to standard — NO new phase)

Use this when you want to bring the site fully up to the current standard and pass every gate, without building the next phase — the site stays on its current phase (foundation).

Automated (recommended)

Run /qa-refresh (or just say “do a QA refresh”) — it runs the qa_refresh workflow for this site, which performs everything below automatically: rewrites every page to standard (incl. hand-authored SVGs and Mermaid→SVG), restyles inline code + homepage + navigation, then builds, fixes until every gate passes, records the uplift and deploys. Direct call:

Workflow({scriptPath: "/home/martin/WebstormProjects/_qa/qa_refresh_workflow.js", args: "waterutility.org"})

Manual (what the workflow does, step by step)

refresh_site does NOT do the uplift for you — YOU must do the actual work first. It is only the bookkeeping/verification step: it re-syncs counts, re-detects the phase (no advance), re-exports this plan, and runs qa_gates. It will refuse to record the uplift unless every gate passes, so you cannot mark a site “uplifted” without having genuinely rewritten the pages and fixed the SVGs.

Do the checklist above but SKIP step 3 (Build the next phase) — i.e. actually rewrite EVERY existing page to the blueprint (2: anatomy, frontmatter, schema, wiki interlinking, hand-authored SVGs, no Mermaid, blended inline code), update homepage & navigation (4), keep it niche-specific (5), term cleanup (6), and pass the SVG + qa_gates checks (7). Then record the refresh and deploy:

.venv/bin/python manage.py refresh_site waterutility.org \
    --blueprint "/home/martin/WebstormProjects/waterutility.org/_plan/blueprint.json"
cd /home/martin/WebstormProjects/waterutility.org
npm run deploy
git add -A && git commit -m "QA refresh (foundation)" && git push

Phase schedule

Priorities for the next phase (expansion)

• Long-tail pages are sparse or absent in the violation-detection-rule-engine-logic pillar clusters (severity-scoring-models, threshold-tuning-frameworks, monitoring-gap-detection-algorithms) — populate these with Python-heavy implementation long-tails first as they carry the highest search intent
• Add a dedicated ‘DMR Generation & SDWIS Submission’ cluster under the compliance taxonomy pillar — Consumer Confidence Reports and Discharge Monitoring Reports are top audience pain points not yet covered as a cluster
• Public notification workflows (Tier 1/2/3 triggers, multi-channel dispatch, state primacy deadlines) represent a high-value cluster gap; add it under the violation-detection pillar
• Audit trail and data lineage pages exist only as pillar-level prose; add long-tail pages covering immutable append-only storage patterns (Parquet on object storage, append-only Postgres) with working Python examples

Page blueprint

(tailored to this site)

• Frontmatter (every page): title, description, slug, type, breadcrumb, datePublished, dateModified
• Schema (JSON-LD): Article, BreadcrumbList, HowTo, FAQPage
• Interlinking: Wiki-style inline interlinking is mandatory. The first mention of any concept that has its own page (protocol, algorithm, model, regulatory construct, pipeline stage) is rendered as a contextual inline hyperlink woven naturally into the sentence — e.g. ‘parsed Modbus registers are routed through the Time-Series Alignment Strategies module’, or ‘before entering the Violation Detection Rule Engine’, or ‘the Monitoring Frequency Scheduling module generates automated sampling calendars’. Every page must also include: (1) an up-link to its parent cluster or pillar in the opening paragraph, (2) 3–6 inline contextual cross-links embedded in body prose, and (3) a short ‘Related’ section at the page foot listing 3–5 sibling or parent pages as plain links. Long-tail pages must always link up to their cluster and to at least one sibling long-tail.

pillar pages (~4500 words)

• H1: descriptive title naming the architectural domain (e.g. ‘Core Architecture & SDWA Compliance Taxonomy’)
• Opening paragraph: operational context — why this domain exists, what problem it solves for water utility engineers and compliance teams; includes up-link to site root

• Foundational Pipeline Architecture: high-level data-flow with a Mermaid flowchart showing the full stage sequence; anchors the taxonomy for the rest of the site

• Regulatory & Standards Foundation: SDWA rule alignment, EPA method codes, state primacy considerations, version-control of rule sets — what federal/state constraints govern this entire domain

• Component Architecture & Data Contracts: the key subsystems, their interfaces, and the data schemas that cross subsystem boundaries; includes inline links to each cluster page

• Security & Operational Technology (OT) Boundaries: network segmentation, least-privilege access, OT/IT convergence requirements specific to this pillar

• Audit Trail & Data Lineage Requirements: immutability, cryptographic checksums, statutory retention periods, chain-of-custody obligations

• Implementation Standards & Tooling: Python libraries, schema enforcement (Pydantic), testing approach, CI/CD considerations

• Jurisdictional & Primacy Variations: state-specific overrides, configurable rule tables, runtime resolution patterns

• Related (end-of-page link block): links to all direct cluster pages and key cross-pillar pages

cluster pages (~3500 words)

• H1: descriptive title naming the cluster’s technical focus (e.g. ‘Modbus TCP Parsing Workflows for Municipal Water Compliance’)
• Opening paragraph: scope — what this cluster covers, who it is for, and an up-link to its parent pillar; includes a Mermaid flowchart of the cluster’s end-to-end workflow

• Regulatory / Protocol Foundation: the specific SDWA rules, EPA analytical methods, or industrial protocol specs that govern this cluster; why these constraints exist

• Architecture & Design Decisions: subsystem design, key design trade-offs, data schemas entering and leaving this cluster; inline links to related clusters

• Phase-by-Phase Implementation: numbered phases (Phase 1…N), each with a prose explanation followed by numbered Implementation Steps and code blocks (Python); Mermaid state or sequence diagrams where appropriate

• Validation, Quality Flags & Edge Cases: range checks, deadband filters, quality-code state machines (Mermaid stateDiagram), leap-year/DST/timezone gotchas, partial-window handling

• Deployment & Integration Patterns: containerization, microservice vs embedded, message broker integration, backpressure handling, read-only filesystem enforcement

• Production Validation Checklist: checkbox list (rendered as interactive checkboxes per site spec) covering every critical configuration item for this cluster

• Failure Modes & Gotchas: the single most consequential misconfiguration risk, with concrete consequences and how to catch it

• Related (end-of-page link block): parent pillar, sibling clusters, and 2–3 long-tail pages within this cluster

long_tail pages (~2000 words)

• H1: specific, actionable title (e.g. ‘Parsing Modbus Registers for Turbidity Sensors’)
• Opening paragraph: problem statement — the exact engineering task, who needs it, and why it matters for compliance; up-link to parent cluster

• Prerequisites & Environment Setup: Python version, library versions (pymodbus, pandas, pydantic etc.), network access, device profile requirements; code block for install commands

• Step-by-Step Implementation: numbered steps with runnable Python code blocks; Mermaid diagram only if a decision branch or state machine adds clarity over prose

• Configuration Reference: key parameters, register maps, scaling coefficients, quality-flag codes — presented as a responsive table

• Verification & Testing: how to confirm the implementation works; unit test snippet; checklist of acceptance criteria (interactive checkboxes)

• Troubleshooting & Gotchas: 3–5 concrete failure modes specific to this task with diagnosis and fix

• Related (end-of-page link block): parent cluster, 2–3 sibling long-tail pages, and one cross-pillar long-tail if applicable

All code blocks must contain valid, production-quality Python — the site spec requires a QA check for valid code and indentation. Mermaid diagrams should always include a %% caption comment. Every Mermaid diagram should be styled to match the site light color scheme. Checkbox lists (Production Validation Checklists) must use ‘- [ ]’ markdown so the 11ty build renders them as interactive checkboxes per the site spec. Inline code spans should NOT use backtick-bordered heavy styling — the site spec calls for light background inline code that blends with surrounding text. KaTeX should be applied to any formula expressing an MCL averaging calculation, statistical threshold (±3σ), or signal scaling equation. Tables must be used for: register maps, MCL reference values, configuration parameters, and quality-flag code definitions — all must be responsive. External links appear ONLY where they already exist in source content (EPA, NIST, Pydantic docs); do not add new external links per site spec.

Custom visuals (SVG)

When upgrading or building any page, add a custom, hand-authored inline SVG wherever a visual would genuinely raise quality (architecture/data-flow diagrams, sequence or state diagrams, comparison matrices, timelines, annotated illustrations). Do NOT add decorative or generic stock-style images. Each SVG must: be original and specific to the page’s content; match the site’s existing design system (colours, fonts, stroke weight); be responsive (viewBox, no fixed pixel width) and accessible (