--- title: Overview --- ```js import {API, POLL_HEAVY, apiFetch, pollDelay, waitForVisible} from "./components/config.js"; import { WORKSTREAM_STATUSES, isClosedWorkstream, isStalledWorkstream, needsReviewWorkstream, normalizeWorkstreamStatus, } from "./components/workplan-status.js"; ``` ```js // Single polling loop — fetches all data in one Promise.all batch, backs off uniformly. const pageState = (async function*() { let failures = 0; while (true) { let summary = {}, snapshots = [], totalPkgs = 0, milestones = [], wsAll = [], ok = false; try { const loadJson = async (name, path, options = {}) => { const response = await apiFetch(path, options); if (!response.ok) throw new Error(`${name} HTTP ${response.status}`); return response.json(); }; const [ summaryData, snapList, allEvents, wsList, taskList, topicList, repoList, workplanIndex, ] = await Promise.all([ loadJson("summary", "/state/summary", {timeout: 20_000}), loadJson("sbom snapshots", "/sbom/snapshots/"), loadJson("milestones", "/progress/?event_type=milestone&limit=500"), loadJson("workstreams", "/workstreams/"), loadJson("tasks", "/tasks/?limit=2000"), loadJson("topics", "/topics/"), loadJson("repos", "/repos/"), loadJson("workplan index", "/workstreams/workplan-index").catch(() => ({workstreams: {}})), ]); ok = true; summary = summaryData; snapshots = snapList; totalPkgs = snapshots.reduce((s, sn) => s + (sn.entry_count ?? 0), 0); milestones = allEvents.filter(e => e.summary?.startsWith("Project registered with State Hub:")); const workplanMap = workplanIndex.workstreams ?? {}; const topicMap = Object.fromEntries(topicList.map(t => [t.id, t])); const repoMap = Object.fromEntries(repoList.map(r => [r.id, r])); const counts = {}; for (const t of taskList) { const wid = t.workstream_id; if (!counts[wid]) counts[wid] = {done: 0, in_progress: 0, blocked: 0, todo: 0, total: 0}; counts[wid].total++; if (t.status === "done") counts[wid].done++; else if (t.status === "in_progress") counts[wid].in_progress++; else if (t.status === "blocked") counts[wid].blocked++; else if (t.status === "todo") counts[wid].todo++; } wsAll = wsList.map(w => { const repo = repoMap[w.repo_id]; const topic = topicMap[w.topic_id]; const workplan = workplanMap[w.id] ?? {}; return { ...w, status: normalizeWorkstreamStatus(w.status), domain: repo?.domain_slug ?? topic?.domain_slug ?? "unknown", repo_label: repo?.slug ?? workplan.repo_slug ?? "unassigned", workplan_filename: workplan.filename ?? null, workplan_relative_path: workplan.relative_path ?? null, workplan_archived: workplan.archived ?? false, health_labels: workplan.health_labels ?? [], href: `./workstreams/${w.id}`, ...(counts[w.id] ?? {done: 0, in_progress: 0, blocked: 0, todo: 0, total: 0}), }; }); } catch (e) { summary = {error: `Dashboard data load failed: ${e?.message ?? String(e)}`}; } failures = ok ? 0 : failures + 1; yield {summary, snapshots, totalPkgs, milestones, wsAll, ok, ts: new Date()}; await waitForVisible(pollDelay({ok, base: POLL_HEAVY, failures})); } })(); ``` ```js const summary = pageState.summary ?? {}; const _ok = pageState.ok ?? false; const _ts = pageState.ts; const totals = summary.totals ?? {}; const ws = totals.workstreams ?? {}; const tasks = totals.tasks ?? {}; const decisions = totals.decisions ?? {}; const wsAll = pageState.wsAll ?? []; ``` ```js // Blocking decisions — fetched once on load, refreshed only after a resolve action. // Kept separate from the main poll so in-progress form inputs aren't wiped every 60 s. const blockingDecisions = Mutable([]); const refreshDecisions = async () => { const r = await fetch(`${API}/decisions/?decision_type=pending`).catch(() => null); const all = r?.ok ? await r.json() : []; blockingDecisions.value = all.filter(d => ["open", "escalated"].includes(d.status)); }; refreshDecisions(); ``` # Custodian State Hub ```js import {injectTocTop} from "./components/toc-sidebar.js"; import {withDocHelp} from "./components/doc-overlay.js"; const _liveEl = html`
● ${_ok ? `Live · updated ${_ts?.toLocaleTimeString()}` : html`Offline — run: cd ~/state-hub && make api`}
`; withDocHelp(_liveEl, "/docs/live-data"); injectTocTop("live-indicator", _liveEl); const _h1 = document.querySelector("#observablehq-main h1"); if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/overview"); } ``` ```js display(html`
⚠️ ${summary.error ?? ''}
`); ``` ## Workstreams by Repository ```js // view() is the idiomatic Observable Framework reactive input: // it displays the element AND returns a reactive value that re-runs dependent blocks. const _chartMode = view(html``); ``` ```js import * as Plot from "npm:@observablehq/plot"; // ── Filter workstreams by selected mode ─────────────────────────────────────── // Lifecycle modes match stored canonical status values. // Health modes are derived labels; they are not stored lifecycle states. // Time modes filter by updated_at / created_at. const _STATUS_MODES = new Set(WORKSTREAM_STATUSES); const _HEALTH_MODES = new Set(["needs_review", "stalled"]); function _timeCutoff(mode) { const now = new Date(); if (mode === "1h") return new Date(now - 60 * 60 * 1000); if (mode === "1d") return new Date(now - 24 * 60 * 60 * 1000); if (mode === "7d") return new Date(now - 7 * 24 * 60 * 60 * 1000); if (mode === "30d") return new Date(now - 30 * 24 * 60 * 60 * 1000); if (mode === "today") return new Date(now.getFullYear(), now.getMonth(), now.getDate()); if (mode === "week") { const d = new Date(now.getFullYear(), now.getMonth(), now.getDate()); d.setDate(d.getDate() - ((d.getDay() + 6) % 7)); // back to Monday return d; } if (mode === "month") return new Date(now.getFullYear(), now.getMonth(), 1); return null; } const _chartWsFiltered = ( _STATUS_MODES.has(_chartMode) ? wsAll.filter(w => normalizeWorkstreamStatus(w.status) === _chartMode) : _chartMode === "needs_review" ? wsAll.filter(needsReviewWorkstream) : _chartMode === "stalled" ? wsAll.filter(isStalledWorkstream) : (() => { const since = _timeCutoff(_chartMode); return wsAll.filter(w => new Date(w.updated_at) >= since || new Date(w.created_at) >= since ); })() ); // Sort by domain, then repository, then most recently updated workstream. // The axis labels show each domain/repo group once. const chartWs = [..._chartWsFiltered].sort((a, b) => { const domainCompare = (a.domain ?? "").localeCompare(b.domain ?? ""); if (domainCompare !== 0) return domainCompare; const repoCompare = (a.repo_label ?? "").localeCompare(b.repo_label ?? ""); if (repoCompare !== 0) return repoCompare; return new Date(b.updated_at) - new Date(a.updated_at); }); // ── Status weight: bold for notable statuses in mixed-status modes ───────────── // Color is NOT used for status — avoids green-on-green when finished bars fill the row. const _isTimeBased = !_STATUS_MODES.has(_chartMode) && !_HEALTH_MODES.has(_chartMode); function _wsWeight(s) { return (isClosedWorkstream(s) || normalizeWorkstreamStatus(s) === "blocked") ? "bold" : "normal"; } // ── y-axis: domain/repo label for first workstream per repository only ──────── const _yLabels = {}; const _seen = new Set(); for (const w of chartWs) { const group = `${w.domain} / ${w.repo_label}`; _yLabels[w.id] = _seen.has(group) ? "" : group; _seen.add(group); } const statusOrder = ["done", "in progress", "blocked", "todo"]; const statusColors = ["#4caf50", "steelblue", "#ff7043", "#e0e0e0"]; const _taskRows = chartWs.flatMap(w => [ {id: w.id, title: w.title, status: "done", count: w.done ?? 0, domain: w.domain, repo: w.repo_label, workplan: w.workplan_filename, href: w.href}, {id: w.id, title: w.title, status: "in progress", count: w.in_progress ?? 0, domain: w.domain, repo: w.repo_label, workplan: w.workplan_filename, href: w.href}, {id: w.id, title: w.title, status: "blocked", count: w.blocked ?? 0, domain: w.domain, repo: w.repo_label, workplan: w.workplan_filename, href: w.href}, {id: w.id, title: w.title, status: "todo", count: w.todo ?? 0, domain: w.domain, repo: w.repo_label, workplan: w.workplan_filename, href: w.href}, ]).filter(d => d.count > 0); function _wsTitle(d) { return [ d.title, `Repo: ${d.repo ?? "unassigned"}`, `Domain: ${d.domain ?? "unknown"}`, `Workplan: ${d.workplan ?? "not file-backed"}`, `${d.status}: ${d.count}`, ].join("\n"); } // ── Render ──────────────────────────────────────────────────────────────────── if (chartWs.length === 0) { const _emptyMsg = { proposed: "No proposed workstreams.", ready: "No ready workstreams.", active: "No active workstreams.", blocked: "No blocked workstreams.", backlog: "No backlog workstreams.", finished: "No finished workstreams.", archived: "No archived workstreams.", needs_review: "No ready workstreams need review.", stalled: "No stalled workstreams — everything is moving.", "1h": "No workstreams changed in the last hour.", "1d": "No workstreams changed in the last 24 hours.", "7d": "No workstreams changed in the last 7 days.", "30d": "No workstreams changed in the last 30 days.", today: "No workstreams changed today.", week: "No workstreams changed this week.", month: "No workstreams changed this month.", }; display(html`

${_emptyMsg[_chartMode] ?? "No workstreams."}

`); } else { display(Plot.plot({ y: { label: null, tickSize: 0, domain: chartWs.map(w => w.id), tickFormat: t => _yLabels[t] ?? "", }, x: {label: "Tasks", grid: true}, color: {domain: statusOrder, range: statusColors, legend: true}, marks: [ Plot.barX(_taskRows, { y: "id", x: "count", fill: "status", title: _wsTitle, href: "href", target: "_self", tip: true, }), // Title label — pushed to lower half of bar row (dy: +7) to separate from count Plot.text(chartWs.filter(w => w.total > 0), { y: "id", x: 0, dx: 6, dy: 7, text: d => d.title.length > 72 ? d.title.slice(0, 70) + "…" : d.title, textAnchor: "start", fontSize: 10, fill: "#1e293b", fontWeight: d => _isTimeBased ? _wsWeight(d.status) : "normal", title: d => [ d.title, `Repo: ${d.repo_label ?? "unassigned"}`, `Domain: ${d.domain ?? "unknown"}`, `Workplan: ${d.workplan_filename ?? "not file-backed"}`, ].join("\n"), href: "href", target: "_self", }), Plot.text(chartWs.filter(w => w.total === 0), { y: "id", x: 0, dx: 6, dy: 7, text: d => `${d.title.length > 48 ? d.title.slice(0, 46) + "…" : d.title} — no tasks yet`, textAnchor: "start", fontSize: 10, fill: "#94a3b8", title: d => [ d.title, `Repo: ${d.repo_label ?? "unassigned"}`, `Domain: ${d.domain ?? "unknown"}`, `Workplan: ${d.workplan_filename ?? "not file-backed"}`, ].join("\n"), href: "href", target: "_self", }), // Count label — pushed to upper half of bar row (dy: -7) to separate from title Plot.text(chartWs.filter(w => w.total > 0), { y: "id", x: "total", text: d => ` ${d.done}/${d.total}`, dx: 4, dy: -7, textAnchor: "start", fontSize: 11, fill: "gray", title: d => `${d.title}\nWorkplan: ${d.workplan_filename ?? "not file-backed"}`, href: "href", target: "_self", }), Plot.ruleX([0]), ], marginLeft: 220, marginRight: 70, height: Math.max(80, chartWs.length * 44 + 50), width: 700, })); } ``` ## Contribution & SBOM Health ```js const contribCounts = summary.contribution_counts ?? {}; const licenceRisk = summary.licence_risk_count ?? 0; const totalContribs = ["br","fr","ep","upr"].reduce((s, t) => s + (contribCounts[t] ?? 0), 0); const needsFollowUp = (contribCounts["submitted"] ?? 0) + (contribCounts["acknowledged"] ?? 0); const sbomSnaps = pageState.snapshots ?? []; const totalPkgs = pageState.totalPkgs ?? 0; display(html`

Contributions

${totalContribs}

${needsFollowUp > 0 ? html`${needsFollowUp} awaiting upstream response` : "all up to date"}

Licence Risk

${licenceRisk}

${licenceRisk === 0 ? html`✓ no copyleft in direct deps` : html`copyleft in direct prod deps`}

SBOM

${totalPkgs.toLocaleString()}

${sbomSnaps.length} repo${sbomSnaps.length !== 1 ? "s" : ""} tracked · ${licenceRisk > 0 ? html`${licenceRisk} copyleft risks` : html`✓ no copyleft`}
`); ``` ## Status ```js const blockedTasks = summary.blocked_tasks ?? []; const wsById = Object.fromEntries((summary.open_workstreams ?? []).map(w => [w.id, w])); const todayCount = (summary.recent_progress ?? []).filter(e => e.created_at?.startsWith(new Date().toISOString().slice(0, 10))).length; const decCount = (decisions.open ?? 0) + (decisions.escalated ?? 0); const statusEl = html`

Active Workstreams

${ws.active ?? 0}

${ws.blocked ?? 0} blocked

Blocking Decisions

${decCount}

${decisions.escalated ?? 0} escalated

Blocked Tasks

${blockedTasks.length}

of ${tasks.total ?? 0} total · click to expand

Events Today

${todayCount}

last 20 shown below
`; statusEl.querySelector('[data-toggle="blocked-panel"]').addEventListener('click', () => { const panel = statusEl.querySelector('#blocked-panel'); const isOpen = panel.style.display !== 'none'; panel.style.display = isOpen ? 'none' : 'block'; statusEl.querySelector('[data-toggle="blocked-panel"] small').textContent = isOpen ? `of ${tasks.total ?? 0} total · click to expand` : `of ${tasks.total ?? 0} total · click to collapse`; }); display(statusEl); ``` ## What's next? ```js // next_steps comes from the summary poll (derived, never persisted) const nextSteps = summary.next_steps ?? []; const typeLabel = { resolved_decision: "Decision resolved", dependency_cleared: "Dependency cleared", unblocked_task: "Task unblocked", }; const typeBadgeClass = { resolved_decision: "ns-badge-decision", dependency_cleared: "ns-badge-dep", unblocked_task: "ns-badge-task", }; if (nextSteps.length === 0) { display(html`

No actionable suggestions right now — all open workstreams are making progress or waiting on decisions.

`); } else { display(html`
${nextSteps.map(s => html`
${typeLabel[s.type] ?? s.type} ${s.domain ?? "—"}
${s.workstream_title ?? "—"}
${s.task_title ? html`→ ${s.task_title}` : ""}
${s.message}
`)}
`); } ``` ## Registered Projects ```js const regs = pageState.milestones ?? []; if (regs.length === 0) { display(html`

No projects registered yet. Run custodian register-project inside a repo.

`); } else { display(Inputs.table(regs.map(e => ({ Project: e.detail?.project_path?.split("/").at(-1) ?? "—", Domain: e.detail?.domain ?? "—", Path: e.detail?.project_path ?? "—", Registered: new Date(e.created_at).toLocaleString(), })), {maxWidth: 900})); } ``` ```js // Registered domains with no workstreams yet — show a getting-started hint const regs = pageState.milestones ?? []; const registeredDomains = new Set(regs.map(e => e.detail?.domain).filter(Boolean)); const emptyRegistered = (summary.topics ?? []).filter(t => registeredDomains.has(t.domain_slug) && (t.workstreams ?? []).length === 0 ); if (emptyRegistered.length > 0) { display(html`
💡 Getting started

These registered projects have no workstreams yet:

`); } ``` ## Blocking Decisions ```js // Uses blockingDecisions (Mutable) — only re-renders when refreshDecisions() is called, // not on every summary poll, so in-progress form input is preserved between polls. const blocking = blockingDecisions ?? []; if (blocking.length === 0) { display(html`

✓ No blocking decisions.

`); } else { for (const d of blocking) { const card = html`
${d.title} ${d.escalation_note ? html`⚠ escalated` : ""} ${d.deadline ? html`Due ${new Date(d.deadline).toLocaleDateString()}` : ""}
${d.description ? html`

${d.description}

` : ""} ${d.rationale ? html`

Context: ${d.rationale}

` : ""} ${d.escalation_note ? html`

${d.escalation_note}

` : ""}
Resolve this decision →
`; // Copy to clipboard const copyBtn = card.querySelector(".r-copy"); copyBtn.addEventListener("click", () => { const parts = [ `# ${d.title}`, "", d.description ?? "", d.rationale ? `\n**Context:** ${d.rationale}` : "", d.escalation_note ? `\n**⚠ Escalated:** ${d.escalation_note}` : "", `\n**Status:** ${d.status} | **Created:** ${new Date(d.created_at).toLocaleDateString()}`, d.deadline ? `**Due:** ${new Date(d.deadline).toLocaleDateString()}` : "", ].filter(Boolean).join("\n"); navigator.clipboard.writeText(parts).then(() => { copyBtn.textContent = "✓ Copied"; setTimeout(() => { copyBtn.textContent = "Copy"; }, 1500); }).catch(() => { copyBtn.textContent = "⚠ Failed"; setTimeout(() => { copyBtn.textContent = "Copy"; }, 2000); }); }); // Resolve const btn = card.querySelector(".r-submit"); const msg = card.querySelector(".r-msg"); btn.addEventListener("click", async () => { const rationale = card.querySelector(".r-text").value.trim(); const decidedBy = card.querySelector(".r-by").value.trim() || "human"; if (!rationale) { msg.textContent = "⚠ Please enter a rationale."; return; } btn.disabled = true; btn.textContent = "Saving…"; try { const r = await fetch(`${API}/decisions/${d.id}/resolve`, { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify({rationale, decided_by: decidedBy}), }); if (r.ok) { await refreshDecisions(); // re-fetches list — resolved decision won't appear } else { const err = await r.json().catch(() => ({})); msg.textContent = `Error ${r.status}: ${err.detail ?? "unknown"}`; btn.disabled = false; btn.textContent = "Record & close"; } } catch (e) { msg.textContent = `Network error: ${e.message}`; btn.disabled = false; btn.textContent = "Record & close"; } }); display(card); } } ``` ## Decisions Due Within 7 Days ```js const in7 = new Date(Date.now() + 7*24*60*60*1000); const due = (summary.blocking_decisions ?? []).filter(d => d.deadline && new Date(d.deadline) <= in7); if (due.length === 0) { display(html`

No decisions due in next 7 days.

`); } else { display(Inputs.table(due.map(d => ({ Title: d.title, Deadline: new Date(d.deadline).toLocaleString(), Status: d.status, })))); } ``` ## Recent Activity ```js display(Inputs.table((summary.recent_progress ?? []).map(e => ({ Time: new Date(e.created_at).toLocaleString(), Type: e.event_type, Author: e.author ?? "—", Summary: e.summary, })), {maxWidth: 900})); ```