generated from coulomb/repo-seed
tegwick
f34b49ebde
S0 — Design boundary formalised across all integration surfaces:
- TOOLS.md restructured with Design Boundary section, Sanctioned Write Tools,
and Bootstrap-Only Tools (create_workstream, create_task) with explicit note
- project_claude_md.template and railiance CLAUDE.md updated with boundary note
and get_next_steps() in session start protocol
- Global ~/.claude/CLAUDE.md updated accordingly
S1 — Workstream dependency graph:
- WorkstreamDependency model (directed edge, CASCADE on delete, unique pair constraint)
- Alembic migration 0b547c153153; script.py.mako added (was missing)
- REST API: POST/GET /workstreams/{id}/dependencies/, DELETE …/{dep_id} (hard delete)
- StateSummary open_workstreams enriched with depends_on/blocks lists
- MCP tools: create_dependency(), list_dependencies()
- Dashboard workstreams page: Dependencies section with relationship cards
- Seeded: custodian-agent-runtime → llm-shared-library + phase-0-operational-baseline
S2 — Suggesting Next Steps (sanctioned write use case #2):
- GET /state/next_steps derives suggestions from recently resolved decisions
(→ first open task in same workstream) and cleared dependencies
(→ first todo task in now-unblocked workstream)
- StateSummary.next_steps included on every summary call
- MCP tool: get_next_steps()
- Dashboard: "What's next?" card grid above Registered Projects
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
16 KiB
16 KiB
title
| title |
|---|
| Overview |
const API = "http://127.0.0.1:8000";
const POLL = 15_000;
// Live polling — yields {data, ok, ts} every POLL ms
const summaryState = (async function*() {
while (true) {
let data, ok = false;
try {
const r = await fetch(`${API}/state/summary`);
ok = r.ok;
data = ok ? await r.json() : {error: `HTTP ${r.status}`};
} catch (e) {
data = {error: "API unreachable"};
}
yield {data, ok, ts: new Date()};
await new Promise(res => setTimeout(res, POLL));
}
})();
const summary = summaryState.data ?? {};
const _ok = summaryState.ok ?? false;
const _ts = summaryState.ts;
const totals = summary.totals ?? {};
const ws = totals.workstreams ?? {};
const tasks = totals.tasks ?? {};
const decisions = totals.decisions ?? {};
// Blocking decisions — fetched once on load, refreshed only after a resolve action.
// Kept separate from the summary poll so in-progress form inputs aren't wiped every 15 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();
// Registered projects — milestone events tagged with registration
const regsState = (async function*() {
while (true) {
let rows = [];
try {
const r = await fetch(`${API}/progress/?event_type=milestone&limit=500`);
if (r.ok) {
const all = await r.json();
rows = all.filter(e => e.summary?.startsWith("Project registered with State Hub:"));
}
} catch {}
yield rows;
await new Promise(res => setTimeout(res, POLL));
}
})();
Custodian State Hub
display(html`<div class="live-bar">
<span style="color:${_ok ? 'var(--theme-foreground-focus)' : 'red'}">●</span>
${_ok
? `Live · updated ${_ts?.toLocaleTimeString()}`
: `<span style="color:red">Offline — run: <code>cd ~/the-custodian/state-hub && make api</code></span>`}
</div>`);
if (summary.error) display(html`<div class="warning">⚠️ ${summary.error}</div>`);
Status
display(html`<div class="grid grid-cols-4" style="gap:1rem;margin-bottom:1.5rem">
<div class="card">
<h3>Active Workstreams</h3>
<p class="big-num">${ws.active ?? 0}</p>
<small>${ws.blocked ?? 0} blocked</small>
</div>
<div class="card ${(decisions.open + decisions.escalated) > 0 ? 'warn' : ''}">
<h3>Blocking Decisions</h3>
<p class="big-num">${(decisions.open ?? 0) + (decisions.escalated ?? 0)}</p>
<small>${decisions.escalated ?? 0} escalated</small>
</div>
<div class="card ${(tasks.blocked ?? 0) > 0 ? 'warn' : ''}">
<h3>Blocked Tasks</h3>
<p class="big-num">${tasks.blocked ?? 0}</p>
<small>of ${tasks.total ?? 0} total</small>
</div>
<div class="card">
<h3>Events Today</h3>
<p class="big-num">${(summary.recent_progress ?? []).filter(e =>
e.created_at?.startsWith(new Date().toISOString().slice(0,10))).length}</p>
<small>last 20 shown below</small>
</div>
</div>`);
What's next?
// 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`<p class="ns-empty">No actionable suggestions right now — all open workstreams are making progress or waiting on decisions.</p>`);
} else {
display(html`<div class="ns-grid">${nextSteps.map(s => html`
<div class="ns-card">
<div class="ns-card-header">
<span class="ns-badge ${typeBadgeClass[s.type] ?? ''}">${typeLabel[s.type] ?? s.type}</span>
<span class="ns-domain">${s.domain ?? "—"}</span>
</div>
<div class="ns-ws">${s.workstream_title ?? "—"}</div>
<div class="ns-task">${s.task_title ? html`→ <strong>${s.task_title}</strong>` : ""}</div>
<div class="ns-msg">${s.message}</div>
</div>
`)}</div>`);
}
Registered Projects
const regs = regsState ?? [];
if (regs.length === 0) {
display(html`<p style="color:gray">No projects registered yet. Run <code>custodian register-project</code> inside a repo.</p>`);
} 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}));
}
Open Workstreams by Domain
import * as Plot from "npm:@observablehq/plot";
const topicById = Object.fromEntries((summary.topics ?? []).map(t => [t.id, t.domain]));
const openWs = (summary.open_workstreams ?? []).map(w => ({
title: w.title,
domain: topicById[w.topic_id] ?? "unknown",
done: w.tasks_done ?? 0,
in_progress: w.tasks_in_progress ?? 0,
blocked: w.tasks_blocked ?? 0,
todo: w.tasks_todo ?? 0,
total: w.tasks_total ?? 0,
})).sort((a, b) => a.domain.localeCompare(b.domain) || a.title.localeCompare(b.title));
const statusOrder = ["done", "in progress", "blocked", "todo"];
const statusColors = ["#4caf50", "steelblue", "#ff7043", "#e0e0e0"];
const taskRows = openWs.flatMap(w => [
{label: w.title, domain: w.domain, status: "done", count: w.done},
{label: w.title, domain: w.domain, status: "in progress", count: w.in_progress},
{label: w.title, domain: w.domain, status: "blocked", count: w.blocked},
{label: w.title, domain: w.domain, status: "todo", count: w.todo},
]).filter(d => d.count > 0);
// y-axis shows domain (only for the first workstream in each domain group)
const yLabels = {};
const _seenDomains = new Set();
for (const w of openWs) {
yLabels[w.title] = _seenDomains.has(w.domain) ? "" : w.domain;
_seenDomains.add(w.domain);
}
if (openWs.length === 0) {
display(html`<p style="color:gray">No open workstreams.</p>`);
} else {
display(Plot.plot({
y: {label: null, tickSize: 0, domain: openWs.map(w => w.title), tickFormat: t => yLabels[t] ?? ""},
x: {label: "Tasks", grid: true},
color: {domain: statusOrder, range: statusColors, legend: true},
marks: [
Plot.barX(taskRows, {y: "label", x: "count", fill: "status", tip: true}),
// Workstream title inside the bar
Plot.text(openWs.filter(w => w.total > 0), {
y: "title", x: 0, dx: 6,
text: d => d.title.length > 36 ? d.title.slice(0, 34) + "…" : d.title,
textAnchor: "start", fontSize: 10, fill: "#333",
}),
Plot.text(openWs.filter(w => w.total === 0), {
y: "title", x: 0, dx: 6,
text: d => `${d.title.length > 24 ? d.title.slice(0, 22) + "…" : d.title} — no tasks yet`,
textAnchor: "start", fontSize: 10, fill: "#aaa",
}),
// "done / total" label after the bar
Plot.text(openWs.filter(w => w.total > 0), {
y: "title", x: "total",
text: d => ` ${d.done}/${d.total}`,
dx: 4, textAnchor: "start", fontSize: 11, fill: "gray",
}),
Plot.ruleX([0]),
],
marginLeft: 160,
marginRight: 70,
height: Math.max(80, openWs.length * 44 + 50),
width: 700,
}));
}
// Registered domains with no workstreams yet — show a getting-started hint
const regs = regsState ?? [];
const registeredDomains = new Set(regs.map(e => e.detail?.domain).filter(Boolean));
const emptyRegistered = (summary.topics ?? []).filter(t =>
registeredDomains.has(t.domain) && (t.workstreams ?? []).length === 0
);
if (emptyRegistered.length > 0) {
display(html`<div class="hint-box">
<strong>💡 Getting started</strong>
<p>These registered projects have no workstreams yet:</p>
<ul>${emptyRegistered.map(t => html`<li>
<strong>${t.domain}</strong> — open repo in Claude Code and say <em>"Hi!"</em> to kick off first session, or run <code>custodian create-workstream --domain ${t.domain} --title "My first workstream"</code> manually
</li>`)}</ul>
</div>`);
}
Blocking Decisions
// 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`<p style="color:green">✓ No blocking decisions.</p>`);
} else {
for (const d of blocking) {
const card = html`<div class="dec-card ${d.escalation_note ? 'dec-escalated' : ''}">
<div class="dec-header">
<span class="dec-title">${d.title}</span>
<span class="dec-meta">
${d.escalation_note ? html`<span class="dec-warn-badge">⚠ escalated</span>` : ""}
${d.deadline ? html`<span>Due ${new Date(d.deadline).toLocaleDateString()}</span>` : ""}
<button class="r-copy" title="Copy decision to clipboard">Copy</button>
</span>
</div>
${d.description ? html`<p class="dec-desc">${d.description}</p>` : ""}
${d.rationale ? html`<p class="dec-context"><strong>Context:</strong> ${d.rationale}</p>` : ""}
${d.escalation_note ? html`<p class="dec-context dec-warn-text">${d.escalation_note}</p>` : ""}
<details class="dec-resolve">
<summary>Resolve this decision →</summary>
<div class="dec-resolve-inner">
<label>Your decision & rationale</label>
<textarea class="r-text" rows="4" placeholder="State the chosen option and your reasoning…"></textarea>
<label>Decided by</label>
<input class="r-by" type="text" value="Bernd">
<div class="dec-resolve-actions">
<button class="r-submit">Record & close</button>
<span class="r-msg"></span>
</div>
</div>
</details>
</div>`;
// 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() || "Bernd";
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
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`<p>No decisions due in next 7 days.</p>`);
} else {
display(Inputs.table(due.map(d => ({
Title: d.title,
Deadline: new Date(d.deadline).toLocaleString(),
Status: d.status,
}))));
}
Recent Activity
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}));