Skip to content

Governance and Constitution

Jump to bottom
Dylan L.R. Pollock edited this page Oct 26, 2025 · 1 revision

Governance & Constitution

Note

This page defines how HueyOS makes and records decisions. It lays out the constitution (clauses, quorum rules), who has what powers (Spark, Zap, Citizens, Workers), and how proposals become actions. It is offline-first and assumes unified memory per Memory-Schema-v2.

Project · Monkey-Head-Project (HueyOS)
Status Date · 2025-10-25
Related · Agent-Citizen-Roles, Governance-Clauses-Registry, Memory-and-Data-Model, Backups-and-Snapshots, Security-and-Operations

1) Principles

  1. Decentralize decision-making, unify memory.
    Power is distributed; the record of truth is singular (events, facts, artifacts).

  2. Governed, not merely programmed.
    Every action traces to a clause and a quorum rule; changes to law are explicit amendments.

  3. Safety first, reversibility second, convenience third.
    Class-A actions require super-majority and Zap greenlight; every change is recoverable from snapshots.

  4. Human-readable by default.
    All decisions produce auditable text logs alongside machine records.

  5. Offline-first.
    No decision depends on an external API being reachable.

2) Roles and powers (constitutional)

Body Powers Limits
Spark Drafts proposals and plans; may propose clause changes No unilateral execution; cannot override Zap veto
Zap Evaluates risk and policy; can veto; gatekeeper for Class-A No vote weight in quorum; must justify veto with clause citation
Citizens (up to 256) Debate, vote, and execute within narrow scopes Vote weight defaults to 1; bound to declared capabilities
Workers Execute approved steps; produce artifacts/logs No vote; must ignore orders missing quorum context

Workers must refuse any Class-A order lacking a quorum record and Zap approval.

6) Records and audits

  • Events — immutable decisions/actions with timestamps and payloads.

  • Facts — time-versioned state; current values derived by latest key, ts.

  • Artifacts — files/blobs with SHA-256; linked back to events.id.

DDL lives in Memory-Schema-v2. Daily signed snapshots per Backups-and-Snapshots.

Audit trail completeness requires: proposal → votes → (optional) veto → quorum evaluation → execute → artifacts → post-mortem fact updates.

7) Amendment process

  1. Draft change — Spark proposes events/proposal/constitution referencing affected clause IDs.

  2. Public text — Full clause text and rationale included in payload; new IDs will be minted.

  3. Review — Citizens debate; Zap checks policy conflicts.

  4. Vote — Super-majority required for any change to governance or safety.

  5. Adopt — Append new clause(s) to clauses.yml; prior IDs remain, marked superseded.

  6. Snapshot — Sign and store updated registry with SHA256SUMS.txt.

Amendments never rewrite existing clause text.

8) Emergency powers

  • Hard E-Stop (CL-0001): Any subsystem may trigger; workers must halt immediately.

  • Incident freeze: Zap can freeze non-essential actions for freeze_ttl while investigation proceeds.

  • Post-incident review: mandatory events/postmortem with contributing factors and corrective actions.

9) Enforcement and appeals

  • Zap veto requires clause citation and a short human-readable reason.

  • Appeal is a new proposal referencing the veto; requires new evidence or altered plan.

  • Abuse control: three consecutive unjustified vetoes trigger a review proposal on Zap’s constraints (still cannot disable Zap).

10) Implementation references

10.1 Message types (canonical)

Proposal

{
  "type": "events/proposal",
  "ts": "2025-10-31T12:00:00Z",
  "actor": "spark",
  "class": "A",
  "title": "Navigate to lab bench and greet",
  "plan": [
    {"do": "path.plan", "args": {"goal": "bench_A"}},
    {"do": "motor.command", "args": {"trajectory_ref": "traj-abc"}},
    {"do": "chat.reply", "args": {"text": "Hello Dylan, ready to begin."}}
  ],
  "clauses": ["CL-0001","CL-0100"]
}

Vote

{ "type": "events/vote", "ts": "2025-10-31T12:00:07Z", "actor": "c010", "proposal_id": "prop-...", "vote": "yes", "weight": 1 }

Veto

{ "type": "events/veto", "ts": "2025-10-31T12:00:08Z", "actor": "zap", "proposal_id": "prop-...", "clause": "CL-0001", "reason": "Obstacle map uncertainty above threshold" }

Execute

{ "type": "events/execute", "ts": "2025-10-31T12:00:10Z", "actor": "c010", "proposal_id": "prop-...", "step": {"do": "motor.command", "args": {"trajectory_ref": "traj-abc"}}, "quorum": {"rule": "Q-DEFAULT", "ayes": 14, "nays": 3} }

10.2 Minimal validator (pseudo)

  • A proposal must:

    • include class, plan[], and clauses[] (IDs must exist)

    • reference only allowed capabilities for its actor

  • An execution must:

    • reference a passing quorum event and (for Class-A) a Zap-greenlight record

    • include proposal_id and step do verb permitted by capabilities map

11) Operational settings (defaults)

governance:
  heartbeat_sec: 2
  proposal_ttl_sec: 15
  vote_ttl_sec: 10
  execute_ttl_sec: 30
  tie_break: "zap_lowest_risk"
  class_a_requires: ["super_majority", "zap_greenlight"]
  storage:
    registry:  "~/huey/config/clauses.yml"
    quorum:    "~/huey/config/quorum.yml"
    caps:      "~/huey/config/capabilities.toml"

12) Compliance checks (runbook)

  1. Registry integrity — sha256sum of clauses.yml matches snapshot manifest.

  2. Quorum sanity — every events/execute within last N hours maps to a passing quorum event.

  3. Zap justification — each veto has a non-empty reason and a valid clause ID.

  4. Worker discipline — no execution without quorum context (scan logs for violations).

  5. Snapshot presence — daily snapshots exist per Backups-and-Snapshots.

13) Example: Class-A motion near people

  1. Spark proposes Class-A motion plan citing CL-0001 and CL-0100.

  2. Citizens vote; Navigation and Perception weigh in.

  3. Zap verifies risk envelope; either approves or vetoes with reason.

  4. If approved and super-majority reached, Workers execute motor commands.

  5. Artifacts (telemetry, video, logs) and hashes persisted; facts updated with final pose.

  6. Post-mortem note added (events/postmortem) with summary and any follow-ups.

14) Change control and releases

  • Governance changes are bundled in releases (see Release-Process) with explicit “Gov:” changelog entries.

  • Each release carries the clause registry, quorum rules, and capability map versions.

  • CI can run a governance linter to prevent pushing inconsistent registries.

15) Security notes

  • Store governance files as read-only for non-owners; changes require signed commits.

  • All decisions are linked to identities (Spark/Zap/cNNN) and traced to a stable clause set.

  • Workers must sandbox IO and ignore orders that cross capability boundaries.

  • See Security-and-Operations for SSH hardening and key management.

Appendix A — Constitution header (machine-readable)

constitution:
  id: "HueyOS-Const-v1"
  effective: "2025-10-31"
  principles:
    - decentralize_decision_unify_memory
    - governed_not_programmed
    - safety_then_reversibility
    - human_readable_by_default
    - offline_first
  registries:
    clauses: "clauses.yml#sha256=<fill>"
    quorum: "quorum.yml#sha256=<fill>"
    capabilities: "capabilities.toml#sha256=<fill>"

Appendix B — Hashing utility (bash)

#!/usr/bin/env bash
set -euo pipefail
file="$1"
sha256sum "$file" | awk '{print $1}'

Cross-references:
For concrete role contracts and examples, see Agent-Citizen-Roles. For migration tasks tied to the October 31 update, see Action-Plan-Oct-31-2025. For the storage schema behind the audit trail, see Memory-Schema-v2.

Clone this wiki locally