Add a live WHI card to the Workstreams page TOC sidebar. All six base
metrics from the spec (workstream-kpi.md) computed client-side from
existing data — no API or schema changes required.
Computation (workstreams.md):
- DD: dependency edges / open workstreams (normalised at DD_crit=1.0)
- BR: blocked workstreams / open workstreams
- SPR: max inbound deps on one incomplete workstream / open count
- PEP: active workstreams with all deps completed / open count
- CDDR: cross-domain edges / total edges
- CPI: DFS cycle detection (back-edge = 1, halves WHI as hard penalty)
- WHI = 0.30(1-DDnorm) + 0.25(1-BR) + 0.15(1-SPR) + 0.20·PEP + 0.10(1-CDDR)
- Per-domain breakdown using intra-domain edges only
Card UI: global WHI % with green/orange/red health label, sub-metric
rows with per-spec warning thresholds, cycle alert panel, per-domain
breakdown rows with coloured dots.
Also add src/docs/workstream-health-index.md reference page (formula,
thresholds, improvement guidance) and wire ? button on the card.
Add "Workstream Health" to Reference nav.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove residual constitution footnote from progress page header
- Create src/docs/decisions.md: types, statuses, resolution history chart,
filter bar, card anatomy, Decision Health KPI, escalation protocol
- Create src/docs/workstreams.md: status distribution chart, filter bar,
table columns, dependency graph, create/update patterns
- Wire withDocHelp(h1) on Decisions and Workstreams pages pointing to new docs
- Add both pages to Reference nav section in observablehq.config.js
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
workstreams: decouple filter form from display (Generators.input pattern);
Status Distribution chart now renders before the filter bar and table.
Dependencies section follows after.
progress: Event Volume chart moved above the filter controls and table;
no reactive changes needed (chart uses raw data, not filtered).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replaces padding-right-only with full padding (0.55rem top/bottom, 0.7rem
left, 1.8rem right). The top padding gives the absolute-positioned ? button
a proper anchor and stops it sitting too low against the text.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- All four pages (index, workstreams, decisions, progress) now inject the
live indicator into #observablehq-toc via injectTocTop("live-indicator", el)
Left-aligned (no text-align: right), position:relative + padding-right for
the ? button affordance
- decisions.md: splits the former combined "decisions-sidebar" widget into two
separate injectTocTop calls — KPI box first (ends lower), live indicator
second (ends at top); both now have their own stable ids
- withDocHelp(_liveEl, "/docs/live-data") wires the ? button on every page
- src/docs/live-data.md: new documentation page explaining poll interval (15s),
indicator colour semantics, offline recovery, and which endpoints each page hits
- Removes the .live-bar CSS class from all pages; replaces with .live-indicator
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Extracts the TOC-injection pattern into a reusable component:
src/components/toc-sidebar.js
injectTocTop(id, element) — prepends an element to #observablehq-toc,
removing any previous instance with the same id first so reactive cells
can re-inject on each poll without accumulating duplicates.
decisions.md now uses injectTocTop to place a single widget (live
indicator + Decision Health KPI box) into the right-column sidebar,
removing the standalone live-indicator cell and the ad-hoc id/remove
pattern that was previously inlined.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Assign a stable id to the KPI element so the previous instance can be
found and removed before the fresh one is prepended to the TOC sidebar.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Inject the KPI box into #observablehq-toc (the framework's right-column
aside) instead of position:fixed. The TOC column already doesn't scroll,
so no CSS tricks are needed. Falls back to a float:right inline block if
the TOC element is absent.
- Remove .kpi-sidebar-outer and its fixed positioning
- Remove min-width/max-width from .kpi-infobox; add margin-bottom to
separate it from the TOC links below
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- `.kpi-sidebar-outer` is now `position: fixed; top: 3.75rem; right: 1.5rem;`
so the Decision Health box stays visible while scrolling
- Re-adds the live indicator as a standalone cell (was accidentally dropped
when the combined `decisions-header` flex layout was removed)
- CSS: replaces `.decisions-header` block with `.kpi-sidebar-outer`;
`.live-indicator` is now standalone (text-align right, margin-bottom)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
KPI infobox
- Replace slim kpi-bar with a boxed card (border, shadow, 195–240px) floating
right in a flex header alongside the live indicator
- Rows: avg resolve time (last ≤5 resolved) + avg open age (all open)
- avg open age colored via CSS var --oc: red/orange/black per threshold
- "no open decisions" shown as muted italic when queue is empty
doc-overlay component (src/components/doc-overlay.js)
- withDocHelp(element, docPath) — adds absolute-positioned ? button
that is invisible until the parent is hovered; click opens overlay
- Overlay: fixed backdrop + animated box with iframe; closes on Esc,
backdrop click, or the close button
- CSS injected once via style tag (STYLE_ID guard, same pattern as MultiSelect)
? buttons wired up in decisions.md
- KPI infobox → /docs/decisions-kpi
- Cumulative chart (wrapped in position:relative div) → /docs/decisions-kpi
- Filter & List section header → /docs/decisions-kpi
Reference page (src/docs/decisions-kpi.md)
- Standalone Observable Framework page at /docs/decisions-kpi
- Documents: KPI card (avg resolve, avg open age, color thresholds),
Resolution History chart (cumulative, period→resolution mapping, filter
interaction, timestamp logic), Filter & List (type/status/search, card
age badge, escalation)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- KPI bar top-right: avg resolution time (last ≤5 resolved decisions)
and avg open age with count; replaces old live-bar with kpi-bar row
- Color logic for avg-open-age KPI:
red — mean open age > avg resolve time
orange — any single open decision exceeds avg resolve time
black — all open decisions younger than avg resolve time
- Decision cards: age badge in header showing "open Xd/h/w" for
open/escalated or "took X" for resolved/superseded; orange when an
open decision has aged past the avg resolve time baseline
- fmtDuration() helper: compact duration formatting (m/h/d/w/mo)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Replace static per-month bar chart with cumulative step-area chart
- Period selector: day / week / month / quarter / YTD / year / all
- Time resolution adapts to period:
day → hours, week → days, month → weeks,
quarter/YTD/year/all → months
- Chart respects the type/status/search filter (uses filtered, not data)
- Chart and period selector appear before the filter form and list
- Use Generators.input() to decouple filter form creation from its
display position; display(_filtersForm) renders it below the chart
- Dots on chart mark buckets where decisions occurred; tip shows delta
- "all" period derives start from earliest decision in filtered set
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Replace Pending/Made tab + Inputs.table with MultiSelect filters and
a proper list view
- Filters: Type (pending/made), Status (open/escalated/resolved/superseded),
title text search — all stable across polls (no data dependency)
- Each decision renders as a compact card: left border coloured by status
(blue=open, amber=escalated, green=resolved, gray=superseded), type and
status badges, domain context, deadline (red+overdue warning if past),
full title, description/rationale snippet, resolved-by attribution
- Decisions sorted: escalated → open → resolved → superseded, then by
deadline ascending within each group
- Fetch now includes topics alongside decisions for domain name join
- Escalation warning box and velocity chart retained
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds src/components/multiselect.js — a compact dropdown multi-select that is
Observable-compatible (exposes .value, dispatches bubbling input events) so it
works with view(), Inputs.form, and Generators.input without modification.
Component behaviour:
- Closed state: pill button showing "Label: All" (muted) or active selection
(1-2 items shown by name, 3+ shown as "N of M"); blue border when active
- Open state: dropdown with per-item checkboxes + "Clear selection" link
(only visible when something is selected); closes on outside click / Escape
- Styles injected once into document.head (STYLE_ID guard prevents duplicates)
- Uses CSS custom properties for light/dark mode compatibility
Workstreams page update:
- Domain and Status filters now use MultiSelect instead of Inputs.checkbox
- Filter bar layout reduced to a tight inline row (0.5rem gap)
- Owner text filter restyled to match trigger button height
- No changes to filter logic or downstream cells (filters.domain / .status
are still string[] with empty = show all)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Replace single-select Domain/Status dropdowns with checkbox multi-selects
- Use Inputs.form() with a custom template to lay the three filters out
side by side in a card-style filter bar
- Filter options are now static constants (DOMAINS, STATUSES) — no
dependency on the polled data, so selections are never reset on refresh
- Empty selection = no filter applied (show all); any checked item = include
- Updated filtered computation and wsWithDeps to use filters.domain /
filters.status array semantics
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Polling fix:
- Blocking decisions now use a Mutable (blockingDecisions) + refreshDecisions()
instead of deriving from summary.blocking_decisions
- Cards only re-render on initial page load or after a successful resolve,
not on every 15 s summary poll — so typing in the form is never interrupted
- On successful resolve, refreshDecisions() re-fetches the list; the resolved
decision no longer matches the open/escalated filter so it disappears cleanly
Copy to clipboard:
- Small "Copy" button in the card header (next to deadline/escalation badges)
- Formats full decision as markdown: title, description, context, status, date
- Shows "✓ Copied" for 1.5 s, reverts to "Copy"; shows "⚠ Failed" on error
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
API:
- DecisionResolve schema (rationale, decided_by, write_log flag)
- POST /decisions/{id}/resolve — marks resolved, emits progress event,
appends entry to DECISIONS.md in the project's registered directory
(found via the topic's registration milestone event)
Dashboard:
- Replace Inputs.table for blocking decisions with full-text cards
- Each card shows title, full description (pre-wrap), rationale/context,
escalation warning if present
- Expandable "Resolve →" section with rationale textarea, decided-by
input, submit button that calls the resolve endpoint
- On success: collapses form, dims card, confirms log was written
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- y-axis tick labels now show domain name (only on the first
workstream in each domain group, blank for subsequent ones)
- Workstream title rendered as text at x=0 inside the bar
- Titles truncated at 36/24 chars to avoid overflow
- marginLeft reduced to 160 (domain names are shorter than titles)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
API:
- WorkstreamWithTaskCounts schema extends WorkstreamRead with
tasks_total/todo/in_progress/blocked/done fields
- /state/summary now includes these counts in open_workstreams via
a single extra GROUP BY query (workstream_id, status)
Dashboard:
- Replace domain workstream-count bar with a horizontal stacked
progress bar per workstream (done/in-progress/blocked/todo)
- Workstreams with no tasks show "no tasks yet" annotation
- Workstreams with tasks show "X/N done" label after the bar
- Sorted by domain then title so domains group naturally
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add follow_redirects=True to httpx Client so 307 redirects (FastAPI
trailing-slash redirects) are followed transparently. Also add trailing
slash normalisation to _get and _patch to match existing _post behaviour,
so all three helpers hit the correct URLs on first attempt.
Requires Claude Code restart to take effect (MCP server is a subprocess
launched at startup).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add one-line imperative at the top of the Session Protocol:
'On receiving your first message — before writing any response text —
call get_state_summary() immediately.'
Previously Claude would wait for a substantive prompt before acting.
Now any first message (including 'start', 'go', or just Enter) triggers
the tool call immediately, after which the First Session Protocol takes over.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
When get_state_summary() shows no workstreams for the domain, Claude
now has explicit instructions: read the canon charter + roadmap, survey
the repo for in-progress work, propose 1-3 workstreams to Bernd, wait
for approval, then create workstreams + tasks and record a milestone.
The "wait for approval before creating anything" gate keeps the human
in control while making the expected first-session behaviour unambiguous.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
MCP server: add create_workstream(topic_id, title, slug?, owner?,
description?, due_date?) — auto-generates slug from title if omitted;
emits workstream_created progress event. Now 12 tools total.
CLI: add two new subcommands —
custodian create-workstream --domain DOMAIN --title TITLE [--slug] [--owner] [--description]
custodian create-task --workstream ID_OR_SLUG --title TITLE [--priority] [--assignee]
create-task accepts workstream UUID or slug (resolves via API).
Dashboard: hint box below "Open Workstreams by Domain" chart listing
registered domains that have zero workstreams, with the exact
custodian create-workstream command to run.
TOOLS.md: updated tool count (11 → 12) and added create_workstream row.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
CORS: add CORSMiddleware to FastAPI for localhost:3000 so browser fetch
works across ports without errors.
All four pages now use async generator cells that call the API directly
and re-yield every 15 s — no data loader cache, no manual cache clearing.
Each page shows a live status bar (● green/red · last updated time).
Offline state shows the `make api` hint inline.
index.md: add "Registered Projects" section — polls
/progress/?event_type=milestone&limit=500 and filters for
"Project registered with State Hub:" events; shows project name,
domain, path, and registration timestamp.
workstreams.md: fix broken domain column — now fetches /workstreams/
and /topics/ in parallel and joins on topic_id client-side.
Previously the domain column showed "unknown" for all rows because
WorkstreamRead schema doesn't include domain.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
custodian register-project [--domain DOMAIN] [--path PATH]
Defaults path to cwd; auto-detects domain from project charter if
--domain is omitted. Does: API health → topic lookup → MCP check →
CLAUDE.md from template → progress event.
custodian status
Prints API health + summary totals + blocking decisions.
Installed via: make install-cli (symlinks .venv/bin/custodian → ~/.local/bin/)
Entry point declared in pyproject.toml [project.scripts].
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
W1: Document user-scope MCP config location in ~/.claude/CLAUDE.md —
adds verification and re-registration commands, warns against
settings.json (saves ~12K tokens per registration session).
W2: scripts/register_project.sh + make register-project —
5-step automation: API health → topic lookup → MCP check →
CLAUDE.md from template → progress event.
W3: state-hub/scripts/project_claude_md.template —
parameterised CLAUDE.md with {PROJECT_NAME}/{DOMAIN}/{TOPIC_ID}
placeholders; used by register_project.sh.
W4: Add custodian_topic_id + domain to all 6 canon project charters —
lets agents grep for topic IDs without touching the API.
W5: state-hub/mcp_server/TOOLS.md — compact 30-line tool reference
card; replaces reading the full server.py (~350 lines).
W6: Switch .mcp.json to absolute path + PYTHONPATH env so cwd is not
required; add scripts/patch_mcp_cwd.py for post-registration fix.
Update ~/.claude.json to match (cwd kept for belt-and-suspenders).
W7 (SessionStart hook) deferred: no SessionStart hook type in Claude
Code; PreToolUse with empty matcher fires before every tool call.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
