Governance Stack Reference

Part of the Hyraxknot Division architecture review, Card 1.
Documents the full governance runtime: lease guard, blocked-card alerting, profile contracts, operation gates, tool registry, handoff guard, evidence ingestion, and scheduled advisory jobs.

Last updated: 2026-07-09
Component of: Governance Layer (Hyrax OS)

---

1. Execution Lease Guard

Source: /root/.hermes/governance/execution_lease_guard.py
Store: /root/.hermes/governance/execution_leases.jsonl

A pure read-only lease detection system that prevents duplicate agent lanes from working the same Linear/Kanban task simultaneously (HYX-222). All detector functions are pure (no I/O) except the store loaders. Mutation operations are not exposed.

Lease States

Valid Claim Sources

• bridge — claimed via the Linear↔Kanban bridge
• kanban_dispatch — claimed via kanban dispatcher
• reader_proposed — proposed by a reader/sister
• manual — manually claimed
• dry_run — report-only proposal (never written to store)

Valid Lease Types

Constants

• Heartbeat stale threshold: 20 minutes
• Default lease duration: 120 minutes (TTL)

Detection Functions

Lease Record Schema (Dry-Run Proposal)

{
    "lease_id": str,                  # UUID v4
    "linear_issue_id": str,
    "linear_issue_identifier": str,   # e.g. "HYX-123"
    "kanban_task_id": str | None,
    "claimed_by_profile": str,        # "tai", "rei", "nei", "mai"
    "claimed_by_gateway": str,
    "claimed_by_session": str,
    "claimed_by_app_actor": str,      # default: "Hyraxknot Agent"
    "claim_source": str,
    "lease_status": str,              # one of VALID_LEASE_STATUSES
    "lease_started_at": str,          # ISO 8601
    "lease_expires_at": str,          # ISO 8601
    "last_heartbeat_at": str,         # ISO 8601
    "heartbeat_source": str,
    "policy_mode": str,               # "report_only" for dry-run
    "duplicate_claim_detected": bool,
    "duplicate_of_lease_id": str | None,
    "evidence_links": list[str],
    "notes": str,
}

JSONL Event Store

The execution_leases.jsonl store records lease lifecycle events, not the lease records themselves. Each line is a JSON event:

Denied lease events have an empty lease_id field.

---

2. Pre-exec Blocked-Card Alerting

Source: /root/.hermes/governance/preexec_blocked_alerts.py
Store: /root/.hermes/governance/preexec_blocked_alerts.jsonl

Addresses the pre-exec blocked-card no-alert bug: when the Kanban pre-exec gate blocks a ready → running transition because the required ## Plan or ## Pre-Execution Plan comment is missing. All detector functions are pure (no I/O) except the store loaders.

Alert States

Required Plan Markers

The pre-exec gate checks for these Markdown headings in a Linear issue’s comments:

• ## Plan
• ## Pre-Execution Plan

Thresholds

Detection Functions

Alert Record Schema

{
    "alert_id": str,                     # UUID v4
    "timestamp_detected": str,           # ISO 8601
    "timestamp_updated": str,            # ISO 8601
    "linear_issue_id": str,
    "linear_issue_identifier": str,      # e.g. "HYX-123"
    "kanban_task_id": str | None,
    "blocked_reason": str,
    "required_marker_missing": str,      # "## Plan" or "## Pre-Execution Plan"
    "card_status": str,
    "linear_status": str | None,
    "assigned_profile": str | None,
    "routing_label": str | None,
    "lease_id": str | None,
    "alert_state": str,                  # one of VALID_ALERT_STATES
    "notification_status": str,          # "report_only" for dry-run
    "evidence_links": list[str],
    "recommended_action": str,
    "notes": str,
}

---

3. Profile Contracts

Source: /root/.hermes/governance/profile-contracts.yaml
Status: Draft, not applied to live profiles.

Defines the intended contractual boundaries for each profile. These serve as review targets for future validation scripts.

hyrax-os (Control Plane)

Allowed CLI toolsets: fleet_audit

Allowed work categories:

• Audit profile configs, tool visibility, governance contracts
• Detect drift, check gateway health, check memory context budgets
• Draft patch proposals, coordinate Codex manual changes
• Prepare script-only cron watchdogs
• Governance audit (fleet, profile, status, gateway classes, operation gates)
• Governance notices (read-only), proactive warnings

Discord notice scope: governance notices only, no chat response, read-only command responder, high-risk proactive notices
Discord runtime status: disabled — Discord gateway for hyrax-os remains disabled until a notice-only wrapper exists

Prohibited work:

• Chat persona routing, affinity state mutation, media/selfie generation, Spotify control
• Governance mutation without contract, fleet ops without Josh approval, fleet ops self-escalation
• Mnemosyne DB mutation, skill tree mutation, sister tool access
• Execution action, lease issuance, handoff note write, proposal approval

Resolver exception (Discord): The kanban toolset may appear on Discord even when platform_toolsets.discord is explicitly empty, due to Hermes recovering non-configurable platform toolsets from the Discord composite. This is accepted only when the Discord gateway is truly disabled and no other Discord toolsets are visible.

Other Profiles (default, rei, nei, tai, mai)

All sister profiles are observed-only. No contracts are enforced on them yet. The contracts document serves as the design target.

Identity Source-of-Truth Rule

Per-profile SOUL.md          = identity source of truth
config.yaml system_prompt    = must NOT contain sister identity/personality content
Shared skills                = must NOT contain personality-defining content
Shared project context       = must be operational only
Identity content             = must be profile-scoped

---

4. Operation Gates

Source: /root/.hermes/governance/operation-gates.yaml
Status: Draft design, not enforced. Mode: read_only_design.

Operation-level gate design for mixed-risk sister-being and work toolsets. Defines how each tool/operation should be gated across profiles.

Scope

• Profiles considered: rei, nei
• Entrypoints considered: cli, discord
• Protected from change: live profile configs, gateway services, Hermes core, plugins, skills, SOUL.md, USER.md, MEMORY.md, Mnemosyne, Discord tokens, tai, mai, default, hyrax-os

Operation Classes (13 classes)

Global Gate Requirements

• Discord: high-risk default for all operations
• No permission expansion by mode changes
• Explicit target required for cross-sister operations
• Audit log required for mutation, generation, admin operations
• Approval required for force override
• Unknown plugins: drift status unless recorded in known_plugin_toolsets and platform_toolsets
• Warning: Hermes currently exposes whole toolsets; several gates require tool-level enforcement

Per-Toolset Gate Analysis

Each toolset is analyzed operation-by-operation with:

• primary_class — the main gate class
• additional_classes — secondary gate classes
• mutability — read_only, bounded_mutating, durable_write, etc.
• state_scope — profile_private, shared_sister, shared_surface, etc.
• required_gates — list of gate conditions
• current_visibility for rei/nei profiles
• current_gate_status — acceptable, violation, insufficient enforcement

Toolset analysis summary:

---

5. Tool Registry

Source: /root/.hermes/governance/tool-registry.yaml
Status: Draft, governance-planning-only.

Defines the effective toolset composition for the hyrax-os control-plane profile.

hyrax-os CLI Toolset

Fleet Control

Policy Enforcement

• Currently disabled (enabled: false)
• Contracts and approval boundaries are not implemented yet

Media & Memory Tools

Validation Targets

The registry identifies these aspects for future validation:

• Effective CLI toolsets
• Effective Discord toolsets (empty or exception-only)
• Disabled plugin toolsets
• Gateway platforms disabled
• Memory context limits
• Profile contract drift

---

6. Sister Label Handoff Guard

Source: /root/.hermes/governance/sister_label_handoff_guard.py
Expected store: /root/.hermes/governance/sister_label_handoff_handoffs.jsonl

Closes the loop between Linear sister routing labels, execution leases, and handoff markers. All detector functions are pure; no mutation or notification.

Sister Labels

sister:rei, sister:nei, sister:tai, sister:mari

Handoff States

detected, acknowledged, resolved, stale, archived

Valid Detector Rules (10 rules)

Detection Functions

Handoff Record Schema (Dry-Run Proposal)

{
    "record_id": str,
    "timestamp_detected": str,
    "timestamp_updated": str,
    "linear_issue_id": str,
    "linear_issue_identifier": str,
    "kanban_task_id": str | None,
    "detector_rule": str,
    "sister_labels_found": list[str],
    "expected_sister": str | None,
    "actual_sister": str | None,
    "lease_id": str | None,
    "handoff_state": str,              # "detected"
    "notification_status": str,        # "report_only"
    "evidence_links": list[str],
    "recommended_action": str,
    "notes": str,
}

Thresholds

---

7. Evidence Ingestion Pipeline

Source: /root/.hermes/governance/evidence_ingest.py

Read-only evidence ingestion from Kanban and Linear. All operations use read-only SQLite (mode=ro) and read-only GraphQL queries. No writes to kanban.db, Linear, or any production store.

Data Sources

Kanban Database (/root/.hermes/kanban.db)

Linear API (https://api.linear.app/graphql)

Fetches the HYX team (team ID: 7bb182c4-1328-42ce-ab7d-c29021adf1a5) issues with:

• Title, state, labels, assignee, creator
• Timestamps (created, updated)
• Up to 10 comments per issue
• Token loaded from /root/.hermes/secrets/linear-app.env

Pipeline Steps (run_ingestion())

1. Kanban schema — introspect table definitions
2. Kanban tasks — read all tasks (redacted)
3. Kanban running tasks — filter running/blocked tasks with run info
4. Linear issues — fetch recent HYX issues via GraphQL
5. Build detector inputs — construct detector_tasks, detector_leases, and linear_comment_map for downstream detectors
6. Snapshots — write redacted JSON snapshots to disk

Detector Inputs

The pipeline produces three data structures for downstream detectors:

• detector_tasks — kanban tasks with extracted Linear references (HYX-### patterns from title, body, comments)
• detector_leases — synthetic lease records from running kanban tasks
• linear_comment_map — {issue_id: [comment_body, ...]} for plan marker detection

Snapshot System

---

8. Scheduled Advisory Jobs

Source: /root/.hermes/governance/scheduled_advisory_jobs.py

Read-only cron runners for governance. No mutations to kanban.db, Linear, or production stores. No notifications. No comments. No label changes.

Job Types

Lock System

Each job uses a PID-based lockfile to prevent concurrent execution:

Locks contain {pid, started_at}. Stale locks are auto-cleared. Locks are released in finally blocks.

Guardrail Summary Output

The guardrails command runs all three G3D-4 detector families:

G3D-4A (Lease Guard):

• Active lease count, duplicates, stale heartbeats, expired, kanban-without-linear

G3D-4B (Pre-exec Alerting):

• Blocked kanban tasks, open Linear issues, issues without plan, ready-state issues without plan

G3D-4C (Handoff Detection):

• Multiple sister labels, missing sister labels, lease-label mismatches

All output is report_only. No enforcement.

Output Directory Structure

scheduled_reports/
├── .locks/
│   ├── ingest.lock
│   ├── guardrails.lock
│   └── audit.lock
├── evidence_snapshot/
│   ├── latest_evidence.json
│   ├── evidence_20260709-120000.json
│   └── ...
├── guardrails/
│   ├── latest_guardrails.json
│   ├── guardrails_20260709-120000.json
│   └── ...
├── audits/
│   ├── latest_audit.md
│   ├── audit_20260709-120000.md
│   └── ...
└── job_log.txt

---

Architecture Diagram: Data Flow

Kanban DB ──┐
            ├──> evidence_ingest.py ──> evidence_snapshots/
Linear API ─┘         │
                      ├──> detector_tasks       ──> sister_label_handoff_guard.py
                      ├──> detector_leases      ──> execution_lease_guard.py
                      └──> linear_comment_map   ──> preexec_blocked_alerts.py
                                                     │
                            scheduled_advisory_jobs.py
                            ├── ingest    (scheduled reports)
                            ├── guardrails (G3D-4A + 4B + 4C summary)
                            └── audit     (work-state audit markdown)

---

Enforcement Status (as of 2026-07-09)

All detectors run in report_only / dry_run mode. No mutations, no notifications, no enforcement are active.

Related Specifications

• Hyrax Contract Advisor Specification
• Essence Relationship Runtime Specification