Scratch for Governance: Visual governance design using ICN domain primitives

[Argocyte]

The Idea

MIT Scratch lets children write real programs by snapping visual blocks together — loops, conditionals, events — without writing a line of code. The blocks are code; Scratch just hides the syntax behind shape and colour.

Governance design has the same problem. A cooperative's constitution is a real, legally-binding program — it defines who can vote on what, under which conditions, with which quorum, with which escalation path. But the interface for composing it is a blank Word document and a solicitor. The legalese is the syntax barrier.

ICN's domain crates suggest a different approach. They already define governance as typed, composable primitives:

• Proposal — a decision with title, description, payload, and approval thresholds
• GovernanceProfile — evaluation rules (quorum, supermajority, consent)
• MembershipConfig — eligibility, tiers, lifecycle states
• GovernanceDomain — a decision space with defined scope and membership
• Charter — institutional rules with amendment and appeal mechanisms
• FederationAgreement — bilateral coordination terms
• DelegationRecord — who authorised what, and from what prior decision

These are not abstractions for their own sake. They are the semantic vocabulary of cooperative law, encoded as machine-readable types.

The proposal: a visual governance design manager where members snap these primitives together — and the system generates the regulatory document, the smart contract parameters, and the platform configuration simultaneously.

---

Why This Is Not Just a Form Builder

A form builder generates a PDF. This is different in three ways:

1. Bi-directional translation

The Genesis boot sequence (already specced in Iskander) reads a cooperative's existing bylaws and extracts governance rules using jurisdiction templates (GB.json for UK BenComs, ES.json for Spanish coops, UNIVERSAL.json for ICA alignment). This is the AI reading into the primitives.

The visual designer is the inverse: members compose governance from primitives, and the AI writes outward into regulatory language. Both directions use the same typed vocabulary. The LLM becomes a translator between human intent and legal form — not the author of governance.

2. The output is not a document — it is a running system

When a member sets a voting threshold in the visual designer:

• Loomio poll settings are updated to match
• The Constitution.sol parameter is updated
• The Clerk agent's SOUL.md is regenerated to reflect the new quorum
• A governance changelog entry is created in the Decision Recorder
• If the threshold change requires a consent decision, the visual designer initiates one before applying the change

The document is a byproduct. The system is the source of truth.

3. Scope-awareness is built in

Each primitive in the visual designer carries a scope (Self, Cooperative, Community, Federation, Commons — see the ICN scope model). A member designing a circle sets its scope; that scope propagates to every decision the circle makes. There is no separate configuration step — governance design and governance execution share the same data model.

---

The ICN Domain Crate Connection

ICN's domain crates are the vocabulary this system needs:

ICN crate	Primitive	Visual block
icn-governance	Proposal, Vote, GovernanceProfile	Decision type block (consent / advice / poll)
icn-governance	MembershipConfig, MembershipTier	Membership tier block
icn-governance	GovernanceDomain	Circle block with scope selector
icn-governance	delegation.rs	Delegation arrow (drag from role to decision domain)
icn-commons	Charter, Amendment, Appeal	Constitution block with amendment process
icn-federation	FederationAgreement	Partner block with trust and clearing terms
icn-community	Community type (geographic, solidarity, ecosystem)	Community relationship block

Iskander does not need to import ICN crates directly (it's Python/Solidity, not Rust). But ICN's type definitions are the schema for the visual blocks. We can implement the same structure in Python (Pydantic models) or TypeScript (Zod schemas) and use ICN's Rust definitions as the canonical reference for correctness.

---

What the Regulatory AI Layer Does

Between the visual designer and the legal document sits an AI layer that:

1. Validates governance designs against jurisdiction-specific requirements (UK BenCom rules, FCA mutual rules, Companies Act constraints) — flags designs that cannot be registered before the member tries
2. Generates regulatory text from primitive compositions — produces a draft constitution or rules document that a solicitor can review, not author from scratch
3. Identifies conflicts — if a member sets a quorum of 80% but also enables a proxy voting block that allows 30% of votes to be cast by a single delegate, the AI flags the tension
4. Maps to existing registrations — for cooperatives already registered with the FCA, Companies House, or equivalent, the AI compares the visual design against the registered document and surfaces diffs that would require a formal amendment

The Genesis boot sequence already implements direction 4 in reverse (reading registered documents into the system). The same LLM chain runs both ways.

---

Prior Art and Inspiration

• MIT Scratch — the visual block metaphor, snap-together primitives that are real code
• Lego Mindstorms — physical blocks generating executable behaviour
• Figma for design systems — components that propagate changes through a system
• OpenLaw / Clause.io — legal document generation from structured data (but not visual, and not cooperative-specific)
• ICN domain crates — the typed cooperative governance vocabulary (github.com/InterCooperative-Network/icn)
• Iskander Genesis boot sequence — AI extraction of governance rules from existing bylaws (docs/archive/2026-03-17-genesis-boot-sequence.md)
• Sociocracy 3.0 pattern library — governance patterns that already function as composable blocks

---

Open Questions

1. What is the right visual metaphor? Scratch uses a palette of coloured blocks. Figma uses a component tree. Miro uses a canvas. Governance design might want a canvas with connectable shapes (circles → roles → decision domains) rather than a linear block palette.

2. Where does the visual designer live? Options:

   • Embedded in Loomio (as a custom governance setup screen)
   • As a standalone Iskander service (governance designer → exports to Loomio config)
   • As a standalone web app that any cooperative can use without Iskander

3. What is the minimum primitive set for MVP? A useful v1 might need only: Circle, Role, Decision type (consent/advice/poll), Quorum threshold, Membership tier. The full ICN vocabulary is the target; MVP needs fewer blocks.

4. How does amendment work? When a cooperative wants to change their governance design, is that a new visual composition (with diff from previous), or an incremental modification? The answer affects how Constitution.sol and the Decision Recorder track governance evolution.

5. What is the relationship to existing cooperative software? CoopCycle, Loomio, Cobudget — these are tools for operating a cooperative. A governance designer is a tool for constituting one. Does the governance designer output configuration for these tools directly?

---

Relationship to Current Iskander Work

This is not a near-term implementation proposal — it's a direction that the current architecture is pointing toward. The pieces already building toward this:

• Genesis boot sequence — AI reads governance documents into typed primitives (the reverse direction)
• Decision Recorder + scope model — typed, scope-tagged records are the runtime representation of the governance design
• ICN architecture reference (docs/reference/icn-architecture-reference.md) — the conceptual vocabulary
• Closure loop (docs/specs/closure-loop-mapping.md) — the nine stations are the runtime behaviour that the visual design describes
• Sociocracy 3.0 templates — S3 circles, roles, and drivers are already governance primitives in document form

The visual governance designer would be the authoring interface for everything Iskander runs. Design it once; run it forever.

---

Call for Input

I'm interested in:

• Prior art in cooperative governance tooling I've missed
• Whether the Scratch metaphor is the right one, or whether there's a better visual model
• Which ICN domain crate primitives would be most valuable to implement first in Python/TypeScript
• Whether there are cooperative practitioners who would use a tool like this — what are the real friction points in governance design today?
• Technical approaches to the bi-directional legal document translation

This is an idea in early development. Discussion and critique welcome.

[Argocyte]

The Legal Bridge Question — Where Governance Documents Live in the System

Following on from the visual governance designer concept here, there's an adjacent question that Phase C needs to resolve: where do governance documents physically live, and how does their adoption become a typed, provenance-tracked event in the system?

This matters for the visual designer too — the design surface you're describing generates documents. Those documents need somewhere to go that isn't a PDF in a Google Drive.

The ICN Closure Loop Gap

ICN's nine-station closure loop has a station most implementations miss:

• Station 5 (Policy): governance decisions produce policy documents
• Station 8 (Receipts): receipts reference the authorising policy

The gap is that in most cooperative software (including early Loomio setups), decisions are recorded but the resulting document — the policy that was adopted — floats free. Nothing links the Loomio vote to the text that was voted on. Over time, you get drift: the vote says "we adopted policy X" but you can't find which version of X, or whether it was ever amended.

Why Nextcloud Solves This Without New Dependencies

I've been looking at FOSS options for the document lifecycle:

Option	RAM	Auth	Member UX
Nextcloud Text + Approve	0 extra (already in stack)	Native Authentik SSO	Familiar (Google Docs-like)
HedgeDoc	~300MB	OAuth config needed	Markdown-only
Forgejo	~200MB	OAuth config needed	Requires git literacy

Nextcloud 28+ ships Text (collaborative Markdown) and the Approve app. The workflow becomes:

1. DRAFT — Clerk creates document in governance/drafts/ via Nextcloud Text
2. SENSE CHECK — Loomio discussion links to the live Nextcloud doc; members annotate
3. VOTED — Loomio proposal; outcome logged to Decision Recorder as governance_adoption type
4. ADOPTED — Clerk moves document to governance/adopted/, tags it, pins an IPFS hash

The IPFS pin is the receipt: you can verify the adopted text cryptographically, the same way Constitution.sol anchors decisions.

The governance_adoption Decision Type

The Decision Recorder needs a new decision type that binds a vote to a document:

decision_type = "governance_adoption"
document_uri = "nextcloud://governance/adopted/policy-X.md"
content_hash = "sha256:..."   # hash of document at adoption moment
ipfs_cid = "Qm..."           # tamper-evident pin
upstream_decision_ids = [42]  # prior decisions this amends
scopes = ["cooperative"]      # ICN scope model

This is the provenance chain ICN is describing in their DelegationRecord and receipt primitives — just implemented in Python against Nextcloud rather than Rust against their storage layer.

Relationship to the Visual Designer

The visual governance designer described in this discussion generates governance configurations. The legal bridge is where those configurations become adopted documents. They're the same pipeline:

Visual designer → draft document → Loomio deliberation → adopted document → typed Decision Recorder entry → IPFS receipt

The ICN scope model propagates through the whole chain: a governance domain designed in the visual tool carries a scope (Cooperative, Federation, etc.), and that scope tag ends up on the adopted document and its Decision Recorder entry.

Filed as issue #113 if this is worth building into Phase C scope.

[Argocyte]

S3 Circles Sidebar — Designed, Awaiting Implementation

Iskander-Code's plan includes a live S3 circles graph sidebar:

• Circle diagram using standard S3 visual language (nested circles, human-readable)
• Active circles highlight when processing, dim when paused
• Constitution + policies visible in panels
• Click any circle to navigate into that domain's chat
• Fractal navigation: click subdomains (smaller circles) to go deeper, parent to go up
• Active domain stays same size in chat — only surrounding context shows scale
• New subdomains appear in real-time when researcher spawns agents

The facilitator emits circle-state events that the interface renders. No LLM needed — purely algorithmic state-to-visual mapping.

ICN's governance primitives inform the visual vocabulary. The 4 ICN CCL governance contracts (sociocracy-consent, consensus-with-fallback, council-delegation, emergency-lock) are already harvested into the project.

This is listed as a remaining tension in docs/open-tensions.md — the architecture is designed but the UI isn't built yet.