Atomizer/projects/hydrotech-beam/dashboard/MASTER_PLAN.md

# Hydrotech Beam — Dashboard & Reporting Master Plan (Multi-LLM Synthesis)

## Purpose
Give Antoine a single, reliable command view of project health while preserving full technical depth and operational traceability.

This plan synthesizes recommendations from:
- Codex 5.3 (execution architecture + contracts + KPI gates)
- Opus 4.6 (PKM-first, markdown-native, low-overhead governance)
- Gemini Pro (clear role-based dashboards + event-stream discipline)

---

## North-Star Architecture (Hybrid, future-proof)

### Phase 1 default (now): **PKM-native dashboards in markdown**
- No new infrastructure required
- Fastest path to value
- Agent-native read/write and auditability

### Phase 2+ extension: **optional web UI over same contracts**
- If/when needed for richer visual analytics
- No rewrite: UI reads the same structured contracts and event logs

**Key principle:** Data contracts first, presentation second.

---

## 1) Information Architecture

## A. Project-specific (lives under `projects/hydrotech-beam/`)
- `dashboard/` — generated dashboard markdown snapshots
- `reports/` — run/phase/executive reports
- `runs/` — run manifests and execution metadata
- `decisions/` — append-only decision records
- `incidents/` — sync/solver/process incident records
- `playbooks/` — project execution procedures

## B. Foundational (lives under `docs/`)
- `docs/guides/` — reusable dashboard/report standards
- `docs/reference/data-contracts/` — versioned schema definitions
- `docs/protocols/` — gates, QA, governance rules
- `docs/templates/` — report and dashboard templates

---

## 2) Dashboard Modules (3-tier)

## A. Executive Dashboard (60-second scan)
- Project status (RAG + phase + blockers)
- Milestone confidence and slip risk
- Decision hotlist (items needing CEO approval)
- Top risks + mitigation owners
- Gate state (Pass / Conditional / Fail)

## B. Technical Dashboard
- DOE/TPE performance (success, feasible points, convergence)
- Constraint panel (disp/stress/geo violations)
- Data quality checks (NaN, stub-vs-nxopen, stale/mixed runs)
- Traceability (requirement → run → result → decision)

## C. Operations Dashboard
- Queue and throughput (WIP, cycle time, backlog)
- Blocker tracker + MTTR
- Review SLA status
- Syncthing/data integrity panel
- Documentation freshness/compliance

---

## 3) Data Contracts (mandatory)

All dashboard/report content must come from structured records with lineage.

Required contracts (v1):
1. `run_manifest.v1.json`
2. `trial_result.v1.json`
3. `study_summary.v1.json`
4. `decision_record.v1.json`
5. `risk_record.v1.json`
6. `gate_evaluation.v1.json`
7. `incident_record.v1.json`

Required fields in every record:
- `schema_version`, `project_id`, `run_id` (if applicable)
- `timestamp_utc`, `owner`, `source_file`, `source_hash`

Ingestion rules:
- Reject invalid schema
- Keep append-only history for decisions/gates/incidents
- Nightly integrity check + drift report

---

## 4) Report System

## A. Daily Ops Brief (auto)
- Blockers, failures, overdue reviews, data integrity warnings

## B. Weekly Executive Brief (auto + curated)
- Milestone confidence, top risks, decision asks, KPI trend deltas

## C. Gate Review Pack (formal)
- Criteria checklist, evidence index, exceptions, sign-offs

## D. Technical Deep Dive (on-demand)
- Methods, assumptions, sensitivity, reproducibility evidence

Render path:
- Markdown source of truth
- Optional HTML/PDF exports from templates
- Immutable snapshot ID per issued report

---

## 5) Governance & Ownership

- **Manager (owner):** documentation architecture, dashboard governance, release quality
- **Tech Lead:** technical KPI definitions, thresholds, validation logic
- **Study Builder:** data pipeline and generators
- **Optimizer:** analytics logic and recommendation layer
- **Auditor:** contract compliance + gate QA

Rule enforced:
- Project-specific content in `projects/...`
- Foundational content in `docs/...`

---

## 6) KPI Set + Gate Rules (starter)

## KPI starter set
- Solve success rate
- Full feasibility rate
- Best feasible mass
- Constraint violation percentiles (disp/stress)
- Data integrity score
- Decision cycle time
- Blocker MTTR
- Documentation freshness lag

## Gate policy
- Gate states: `PASS` | `CONDITIONAL_PASS` | `FAIL`
- Conditional pass requires named owner + due date + risk acceptance
- Hard fail blocks progression

DOE→TPE gate (initial):
- Solve success ≥ 80%
- Feasible points ≥ 5
- Data integrity score ≥ 95%

---

## 7) Rollout Plan

## Phase 0 (48h)
- Contract definitions + KPI dictionary
- Dashboard markdown templates
- Run manifest/logger enabled

## Phase 1 (1 week)
- Live executive + operations dashboards
- Daily ops brief + weekly executive brief

## Phase 2 (2–3 weeks)
- Technical dashboard depth (DOE/TPE analytics, traceability)
- Gate review packs with evidence linking

## Phase 3 (ongoing)
- Optional web UI layer
- Predictive risk signals and anomaly detection

---

## 8) Risks & Mitigations

1. Backend confusion (stub vs nxopen)
- Mitigation: manifest hard-check + dashboard alert

2. Syncthing conflicts / stale truth
- Mitigation: conflict detector + incident workflow

3. Schema drift
- Mitigation: versioned contracts + validator + auditor checks

4. Dashboard sprawl
- Mitigation: role-based views + KPI change control

5. Documentation decay
- Mitigation: freshness SLA + automated stale flags

---

## Decision
Proceed with **PKM-native dashboard/report system now**, built on strict contracts and governance, with a clean upgrade path to richer UI later.