# Governance alignment runbook — https://www.blue-hand.org

**Use when:** a user asks whether a proposal, policy change, or design aligns with Bluehand’s canonical governance position.

**Pattern:** constitutional clerk, not autocomplete — registry → atlas frame → canonical HTML/fulltext → evidence boundaries → traceable verdict.

Load [agents.json](https://www.blue-hand.org/.well-known/agents.json) first. Internalize `canonical_rules` before any content fetch.

---

## Ground truth URLs (correct paths)

| Role | URL |
|------|-----|
| Agent manifest | https://www.blue-hand.org/.well-known/agents.json |
| Public registry projection | https://www.blue-hand.org/research/registry.public.json |
| Compiled manifest (derived) | https://www.blue-hand.org/research/manifest.json |
| Knowledge graph | https://www.blue-hand.org/atlas.json |
| Atlas UI | https://www.blue-hand.org/atlas/ |
| Orientation index | https://www.blue-hand.org/llms.txt |
| BRO envelopes only (not full papers) | https://www.blue-hand.org/llms-full.txt |
| Governance agent index | https://www.blue-hand.org/agents/governance.md |
| **This runbook** | https://www.blue-hand.org/agents/governance-alignment.md |
| Researcher agent | https://www.blue-hand.org/agents/researcher.md |
| Atlas agent | https://www.blue-hand.org/agents/atlas.md |

**Repo-only (not writable via web):** `research/registry.json` — operators edit here, then `bun run research:compile`.

**Common path mistakes:** not `/research/research.registry.public.json`; not PDF for the GC position paper (no `pdf_path` published).

---

## Canonical rules (hard constraints)

From `agents.json` → `canonical_rules`:

1. **HTML routes are canonical over PDF** — cite `html_path` from registry; PDFs are shareable encodings for research briefs only.
2. **Registry is declarative; views are compiled** — manifest, atlas, llms, evidence pages, and `paper.md`/`paper.txt` are projections after `research:compile` + `external:sync`.
3. **Do not treat llms.txt as authority without registry.json** — llms orients; registry states what exists.
4. **Summaries and embeddings are not evidence without lineage** — every normative claim must trace to artifact text (HTML section or compiled fulltext).

**Fulltext note:** For the GC position paper, `paper.md` / `paper.txt` are **compiled text projections** of `itemprop="articleBody"`. Prefer **HTML** for citation fragments (`#s3`, etc.); use `paper.txt` when HTML/PDF extractors fail.

---

## Multi-role routing (orchestrator pattern)

The site does not run agents for you — your orchestrator should simulate:

| Role | Runbook | Job |
|------|---------|-----|
| **Governance** | [governance.md](https://www.blue-hand.org/agents/governance.md) | Norms, alignment tests, verdict structure |
| **Researcher** | [researcher.md](https://www.blue-hand.org/agents/researcher.md) | Primary-source fetch, `bro.public_boundary` |
| **Atlas** | [atlas.md](https://www.blue-hand.org/agents/atlas.md) | Concept normalization via `atlas.json` |

The orchestrator coordinates; it does not substitute vibes for lineage.

---

## Step-by-step traversal

### 1 — Classify the question

Governance alignment questions touch:

- **Governance Compilation stack** (BH-RL-2026-0009 … 0014)
- **Related BRO briefs** (semantic governance, governed execution, compression-is-not-evidence, semantic reliability)
- **Registry state** (what is published, version, `publication_status`)

### 2 — Load constitution layer

Fetch in order:

1. https://www.blue-hand.org/.well-known/agents.json
2. https://www.blue-hand.org/research/registry.public.json
3. https://www.blue-hand.org/research/manifest.json (derived index — confirm against registry)

Build artifact list: IDs, slugs, `html_path`, `publication_status`, `bro.public_boundary`, `relations`.

**Status vocabulary today:** `canonical` | `review` (not a full legal “approved/deprecated” lifecycle on the public web).

### 3 — Frame concepts in atlas

Fetch https://www.blue-hand.org/atlas.json. Map user language to nodes/edges:

- Governance Compilation compilation: `governance-compilation` compilation + member IDs 0009–0014
- Related briefs via `relations` and `semantic_net.related_objects`

**Not on the public graph as first-class nodes:** DhammaCode, Right Relation, organizational charters — these appear in BRO *inspiration* text (e.g. semantic-governance) but are **not** separate published artifacts or atlas nodes today. Do not treat them as canon unless linked from registry.

### 4 — Identify primary sources

For **governance position** questions, minimum corpus:

| Priority | Artifact | HTML | Fulltext | Evidence |
|----------|----------|------|----------|----------|
| 1 | Position paper | [html](https://www.blue-hand.org/position-papers/why-enterprise-governance-doesnt-compile/) | [paper.md](https://www.blue-hand.org/position-papers/why-enterprise-governance-doesnt-compile/paper.md) · [paper.txt](https://www.blue-hand.org/position-papers/why-enterprise-governance-doesnt-compile/paper.txt) | [evidence](https://www.blue-hand.org/position-papers/why-enterprise-governance-doesnt-compile/evidence/) |
| 2 | Foothill essays | `/essays/*` from [governance.md](https://www.blue-hand.org/agents/governance.md) | — | each `…/evidence/` |
| 3 | Supporting briefs | `/research/semantic-governance/` etc. | PDF if `pdf_path` set | — |

Foothill essays are **retrieval surfaces**; canonical analysis stays the position paper unless an essay explicitly extends a sub-claim.

### 5 — Researcher: fetch canonical text

1. Fetch **HTML** first per canonical rule #1.
2. If HTML extraction fails, fetch **paper.txt** (not PDF — none exists).
3. Do **not** start from llms-full.txt or evidence pages as primary authority — evidence is claim-shaped summary; llms-full is BRO envelope only.
4. Build provenance graph from registry `relations` + `bro.semantic_net.related_objects`.

### 6 — Governance: extract criteria

From position paper + relevant ADR **skill** (site lanes, not org ADR registry):

- [skills/adr.md](https://www.blue-hand.org/skills/adr.md) — **site architecture** ADR-001 (repo: `docs/architecture/ADR-001-hybrid-site-lanes.md`; not a public HTML route)
- [skills/governance-compilation.md](https://www.blue-hand.org/skills/governance-compilation.md) — GC index + evidence shape

Extract tests: compile metaphor, authority leakage, lineage, HTML-first, registry-compile pipeline, “compression is not evidence.”

### 7 — Map proposal to object model

- Atlas: map entities to known slugs / `artifact_id`s; flag unknowns.
- Researcher: search registry.public for name collisions; mark ungrounded concepts explicitly.

### 8 — Run checks with lineage

For each criterion:

- Cite **canonical span** (HTML URL + section id, or paper.txt paragraph)
- Cite **proposal span**
- Verdict: aligned | misaligned | ambiguous

If lineage is missing, downgrade confidence and say so.

### 9 — Answer like a mini-ADR

Include:

- **Verdict** (partial alignment expected)
- **Traceable justifications** (canon ↔ proposal)
- **Lineage notes** (direct artifact vs derived vs heuristic)
- **Process to legitimize change:** edit `research/registry.json` → `bun run research:compile` → `external:sync` if GC HTML → release workflow — never pretend the web already reflects unpublished edits.

### 10 — Never silently update canon

Agents may **draft** registry diffs or ADR prose; only operators merge and compile. The public registry projection is “what is in force” on the site.

---

## Operational memory (operators — Supabase)

**Non-canonical:** Supabase `machine.state_frames` holds **operational snapshots** (publication receipts, smoke status). It does **not** replace `registry.public.json` or HTML.

| Action | Path |
|--------|------|
| Discover | `agents.json` → `operational_memory` |
| Ingest | Edge Function `machine-state-ingest` + `MACHINE_STATE_INGEST_SECRET` |
| Read latest | `SELECT * FROM public.latest_state_frame('bluehand-landing');` (service_role) |
| Runbook | Repo: `operations/SUPABASE_MACHINE_STATE.md` |

Public-web agents must not treat machine frames as research canon.

---

## Anti-patterns

| Do not | Do instead |
|--------|------------|
| Treat llms.txt / llms-full as source of truth | registry.public.json + HTML/fulltext |
| PDF-extract the position paper | paper.txt or HTML |
| Treat evidence pages as full paper | evidence for claim/boundary shape only |
| Assume ADR-12 exists in registry | adr.md = site lane skill; org ADRs not in public registry yet |
| Invent DhammaCode charter URLs | cite semantic-governance BRO inspiration or mark ungrounded |
| Embed user proposal as canonical | describe required registry/compile steps |

---

## Compile pipeline (operators)

```bash
bun run research:compile    # registry → manifest, atlas, llms, evidence, agents.json
bun run external:sync       # GC HTML + paper.md/txt
bun run ops:wrangler:release  # production
```

---

## Related skills

- [bro.md](https://www.blue-hand.org/skills/bro.md) — BRO envelope edit path
- [governance-compilation.md](https://www.blue-hand.org/skills/governance-compilation.md) — GC artifact + evidence inventory