Files

tegwick a5fa4177af Implement State Hub v0.2: dependency graph, next-steps suggestions, design boundary

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>

2026-02-25 23:33:14 +01:00

4.1 KiB

Raw Blame History

State Hub MCP — Tool Reference Card

Quick reference for all tools and resources.

Design Boundary

The State Hub is a read model. It observes and visualises cross-domain state that originates in the projects themselves.

Two write operations are permanently sanctioned:

Use Case	Tools
Resolving Decisions	`resolve_decision()` — decisions are cross-cutting; resolution must propagate across all domains
Suggesting Next Steps	`get_next_steps()` (v0.2) — surface what is unblocked; the domain does the work

All other mutate tools are bootstrap-only: use them during First Session Protocol to give a freshly-registered project its initial workstream structure. Do not use them as a substitute for formal work definition inside the domain repo.

Query Tools (read-only, use freely)

Tool	Key Args	When to use
`get_state_summary()`	—	Session start. Full snapshot: totals, blocking decisions, blocked tasks, open workstreams, last 20 events.
`get_topic(slug)`	`slug`: e.g. `"markitect"`	Deep-dive on one topic + its workstreams + recent events.
`list_blocked_tasks(workstream_id?)`	optional filter	Surface all impediments, optionally scoped to one workstream.
`list_pending_decisions(topic_id?)`	optional filter	Decisions holding up work, sorted by deadline.
`get_recent_progress(limit, since?)`	`limit` default 20; `since` ISO datetime	Reconstruct recent session history.

Sanctioned Write Tools

Tool	Key Args	Notes
`record_decision(title, ...)`	`decision_type`: made/pending; `topic_id?`; `workstream_id?`; `deadline?`	Financial/legal + pending → auto-escalated per constitution §4. At least one of topic_id/workstream_id required.
`resolve_decision(decision_id, rationale, decided_by)`	all required	Marks decision resolved, emits progress event, writes DECISIONS.md to project directory.
`add_progress_event(summary, ...)`	`event_type`: note/milestone/blocker/insight; `topic_id?`; `workstream_id?`; `task_id?`; `detail?`	Append-only log entry. Use at session end.

Bootstrap-Only Tools

Use during First Session Protocol to give a freshly-registered project its initial workstream structure. Do not use for ongoing project management — formal work structure belongs in the domain repo (workplans, requirements, milestones).

Tool	Key Args	Notes
`create_workstream(topic_id, title, ...)`	`slug?`; `owner?`; `description?`; `due_date?`	Creates workstream under a topic. Use `get_state_summary()` to find topic IDs.
`create_task(workstream_id, title, ...)`	`priority`: low/medium/high/critical; `assignee?`; `due_date?`	Creates task under a workstream.
`update_task_status(task_id, status, ...)`	`status`: todo/in_progress/blocked/done/cancelled; `blocking_reason` required when blocked
`update_workstream_status(workstream_id, status)`	`status`: active/blocked/completed/archived

Resources (URI-addressable, read-only)

URI	Returns
`state://summary`	Full StateSummary JSON
`state://topics`	Active topics list
`state://workstreams/{topic_slug}`	Workstreams for a topic (by slug)
`state://decisions/blocking`	All pending decisions
`state://tasks/blocked`	All blocked tasks

Domain Slugs

custodian · railiance · markitect · coulomb-social · personhood · foerster-capabilities

Common Patterns

# Session start:
get_state_summary()

# Decision resolved in the hub UI or via tool:
resolve_decision(decision_id="<uuid>", rationale="...", decided_by="Bernd")

# Session end:
add_progress_event(
    summary="...",
    event_type="note",          # or milestone / insight / blocker
    topic_id="<uuid>",
    workstream_id="<uuid>",     # optional
    detail={"key": "value"},    # optional
)

# First Session Protocol only — bootstrap a new project:
create_workstream(topic_id="<uuid>", title="My Workstream", owner="me")
create_task(workstream_id="<uuid>", title="Do the thing", priority="high")

4.1 KiB Raw Blame History