governed-console

Governed Console — read, reason, dry-run, hand off

This plugin's governed-universe MCP server is the agent-facing operating console over a governed Growthub workspace. It exposes read + dry-run + governed hand-off, never a mutation tool. The workspace (its API routes) owns reality; the console exposes understanding of it.

The server runs growthub serve --mcp against the current project (${CLAUDE_PROJECT_DIR}), which must contain a growthub.config.json at the root or under apps/workspace/. If neither exists, the tools will report the missing config — this plugin is for operating exported/forked governed workspaces, not arbitrary repos.

The operating loop

Every workspace task follows the same explicit loop:

read → reason → dry-run → governed hand-off → re-read → continue

1. Read — describe_workspace to orient, then the list_* tools for the area you are touching.
2. Reason — describe_node, find_downstream_dependencies, simulate_causal_impact, trace_lineage before changing anything.
3. Dry-run — preflight_patch with the exact PATCH body you intend to send. Never skip this.
4. Governed hand-off — next_actions emits the exact sanctioned route (PATCH /api/workspace, sandbox-run, workflow/publish, helper/apply). Execute that route yourself through the workspace API — the MCP server never mutates.
5. Re-read — after the governed change lands, read again. In --live mode the server rehydrates per call, so reads are never stale.

Tool inventory (14 tools, by control-plane layer)

Layer 3 — Intelligence (read-only, no side effects):

Tool	Answers
describe_workspace	identity, capabilities, object/edge counts, provenance
list_data_model	objects + fields, types, isLiveBacked, row counts, views
list_dashboards	dashboards + widgets, bindings, required fields, warnings
list_workflows	workflows + nodes, lifecycle, required inputs
list_integrations	integrations, sandboxes (authStatus — never secrets), source records
outcome_ledger	runs, pipeline health, artifacts, provenance (session continuity)
describe_node	one node: summary + direct dependents/dependencies + enrichment
get_workspace_topology	the full metadata graph (nodes + edges)
find_downstream_dependencies	blast radius — the transitive dependent set
simulate_causal_impact	stale surfaces + workflow impact of changing a node
trace_lineage	provenance closure — prefer dependents / dependencies directions
app_readiness	ship-readiness verdict { ready, blocking[], nextAction }

Layer 2 — Law (dry-run only): preflight_patch — tests the exact PATCH body against the allowlist, blast radius, and contract compliance. With a live runtime it proxies the authoritative POST /api/workspace/patch/preflight route (forwarding appScope as x-growthub-app-scope); offline it is a clearly-labelled approximation (mode field tells you which you got).

Layer 1 — Mutation: none. next_actions emits the exact governed call to run; there is no third mutation path.

Correct usage patterns

• Before deleting or editing a business object — describe_node + find_downstream_dependencies on it, then preflight_patch the removal. Removal warnings and stale surfaces come back before anything breaks.
• Before shipping — app_readiness, then work the blocking[] list via next_actions.
• Debugging a broken dashboard — list_dashboards (widget warnings) → describe_node on the widget → trace_lineage to what backs it.
• Session continuity — start with outcome_ledger to read what previous sessions did (runs, receipts, artifacts) before acting.

Live mode

The shipped server config is offline-first: it reads the repo artifact (growthub.config.json + growthub.source-records.json sidecar). When the workspace dev server is running (typically http://127.0.0.1:3777), point the console at it so Intelligence reads reflect live state and preflight_patch proxies the authoritative Law route — override the server in your project's .mcp.json:

{
  "mcpServers": {
    "governed-universe": {
      "command": "npx",
      "args": ["-y", "@growthub/[email protected]", "serve", "--mcp",
               "--fork", ".", "--live", "http://127.0.0.1:3777"]
    }
  }
}

Every tool result carries source (offline-config, live:<url>, or offline-fallback (...)) and snapshotAt — trust what the tool says it read, and say so in your own reporting.

Boundaries (must hold)

• Never treat the console as a write API — mutations go through the governed workspace routes only (see the governed-workspace-mutation skill in this plugin).
• Never skip preflight_patch before a PATCH.
• Never print secrets; the console exposes authStatus, not tokens.
• If a tool reports offline-approximation, do not present its verdict as the authoritative Law result — boot the workspace and use --live for authority.