Reference Implementation

8.0 Preamble

Justification

A protocol without an implementation is untested theory. Sections 1 through 7b define what a conforming node MUST do — state partitions, provenance chains, decay/renewal, the evolution path, colony coordination, fault isolation. But none of those sections prove the protocol is implementable with current technology. Three claims in particular require a concrete demonstration:

Conventions-as-architecture works. The entire Synixolis protocol can be expressed as markdown files that an agent reads, follows, and evolves. No custom runtime, no compiled binary, no database engine. The protocol IS the text.
Markdown files can serve as the state store. The five metabolic regions, the eval trace log, the colony manifest, the maintenance queue — all of these can be implemented as structured markdown files on a filesystem, with the agent as the only process reading and writing them.
Claude Code’s plugin system provides sufficient primitives. A CLAUDE.md file for protocol rules, a .claude/commands/ directory for slash commands, and filesystem access for state — these three primitives are enough to instantiate a fully conforming node.

The reference implementation proves these claims by construction. It also serves as the bootstrap template — anyone who wants a conforming node copies this directory, sets their priors, and runs /status to verify.

Operating Timescale

The implementation itself is static — the directory structure, the CLAUDE.md content, and the slash command definitions change only on release. But the operations the implementation exposes span every timescale the protocol defines:

Timescale	Operations Exposed
Per-operation (ms)	Schema validation, provenance chain checks, invariant enforcement (triggered on every `/memory-write`)
Per-interaction (seconds)	Write path (`/memory-write`), read path (`/query`), action cascade routing
Per-session (minutes to hours)	Session-start sync, session-end flush, heartbeat write, ephemeral expiry
Periodic (hours to days)	Decay pass (`/memory-review`), condensation check (`/reflect`), housekeeping (`/housekeeping`)
Lifecycle (days to weeks)	Structural renewal audit, provenance audit, convention review (`/evolve`)
Evolution (weeks to permanent)	Protocol evolution via `/evolve` — trace, analyze, propose, compile, demote

Distributed Systems Framing

The reference implementation instantiates a single node in a distributed system. Even a standalone node uses DS primitives — it is a degenerate colony of size 1 that MAY grow.

Implementation Element	DS Concept
Bootstrap procedure	Node bootstrap — new participant joins a cluster by loading a checkpoint and replaying the log tail
Heartbeat write (per-interaction)	Heartbeat / lease — liveness assertion that renews the node’s lease on ACTIVE status
`colony/channels/`	Message passing — typed communication channels between nodes (pub/sub with structured message envelopes)
`colony-state/log.md` + materialized views	State replication — replicated append-only log with local projections (event sourcing + materialized views)
`colony-state/checkpoints/`	Checkpointing — periodic state snapshots for bootstrap and fault recovery (Chandy-Lamport simplified)
`fault-isolation/invariants.md`	Admission control — per-operation validation gates that reject malformed state transitions

8.1 Directory Structure

A conforming single-node implementation MUST maintain the following filesystem layout. This is the complete on-disk representation of a node’s state, protocol, and coordination infrastructure.

synixolis-node/
├── CLAUDE.md                         # Protocol core — the agent's operating instructions
├── .claude/
│   ├── settings.json                 # Claude Code permissions (tool access, file scope)
│   └── commands/
│       ├── memory-write.md           # /memory-write — Write Path (§3.3.1)
│       ├── memory-review.md          # /memory-review — Maintenance Path (§3.3.3)
│       ├── reflect.md                # /reflect — Condensation (§3.3.3 Stage 3)
│       ├── query.md                  # /query — Read Path (§3.3.2)
│       ├── status.md                 # /status — Health dashboard
│       ├── evolve.md                 # /evolve — Evolution Path (§3.3.4)
│       └── housekeeping.md           # /housekeeping — Link audit, expiry, archive
├── memory/
│   ├── ephemeral/                    # Minutes–hours. Hard-expire at TTL.
│   ├── operational/                  # Days–weeks. Active confidence decay.
│   │   ├── observations.md           #   Append-only raw observations
│   │   ├── action-items.md           #   Tasks with deadlines
│   │   └── threads/                  #   Raised patterns (Zettelkasten-style)
│   ├── structural/                   # Months–quarters. Periodic review cycle.
│   │   ├── entities.md               #   People, projects, systems
│   │   ├── architecture.md           #   Decisions, patterns, constraints
│   │   └── threads/                  #   Consolidated knowledge threads
│   ├── identity/                     # Permanent until explicitly changed. Human-gated.
│   │   ├── core.md                   #   Mission, values, non-negotiable constraints
│   │   └── principles.md             #   Operating principles
│   └── glacier/                      # Archived. Indexed. Never deleted.
│       └── index.md                  #   Retrieval index for archived entries
├── eval/
│   ├── traces.md                     # Append-only interaction traces (§3.6)
│   ├── query-log.md                  # Reads-as-writes log (§3.3.2 Stage 3)
│   └── compiled-rules.md            # Level 2 compiled conventions with provenance + τ*
├── colony/
│   ├── manifest.md                   # This node's identity (receptor, charter, scope, state, heartbeat)
│   ├── channels/                     # Message channels for inter-node communication
│   ├── steering.md                   # Human-provided colony constraints
│   └── maintenance-queue.md          # Persistent task queue (§6c.4)
├── colony-state/
│   ├── log.md                        # Append-only state transition log (source of truth, §6b)
│   ├── shared-structural/            # Materialized view of shared structural entries
│   ├── shared-identity/              # Materialized view of shared identity entries
│   ├── conventions/                  # Materialized view of colony-wide compiled rules
│   └── checkpoints/                  # Periodic snapshots for bootstrap + rollback
├── fault-isolation/
│   ├── invariants.md                 # Hardwired validation rules — Layer 1 (§7b)
│   ├── fault-signatures.md           # Learned fault signatures with provenance + τ* — Layer 2
│   ├── incident-log.md               # Append-only fault event record (tamper-evident)
│   └── audit-schedule.md             # Provenance audit schedule + results
└── protocol/
    ├── changelog.md                  # Every convention/policy change logged (§5.4)
    ├── conventions.md                # Compiled routing rules — Level 2 (§4, §7)
    └── hardwired.md                  # Immutable core (provenance, traces, escalation gates)

Directory Semantics

Each top-level directory corresponds to a distinct subsystem of the node contract:

Directory	Subsystem	Persistence Model
`memory/`	State partitions (§3.1)	Read/write. Region-specific lifecycle (decay, renewal, archival).
`eval/`	Telemetry (§3.6)	Append-only. Never modified in place. Retention per §3.6.
`colony/`	Node identity + coordination (§6)	Read/write. Manifest updated per-interaction (heartbeat).
`colony-state/`	Shared state replication (§6b)	Log is append-only. Views are rebuilt from log. Checkpoints are periodic snapshots.
`fault-isolation/`	Fault detection + response (§7b)	Invariants are static. Signatures and incident log are append-only.
`protocol/`	Convention lifecycle (§7)	Changelog is append-only. Conventions are read/write (evolution path). Hardwired is read-only.

Structural Invariants

Every file listed above MUST exist at node initialization, even if empty. A conforming node MUST NOT operate with a partial directory structure — missing files indicate incomplete bootstrap.
Append-only files (eval/traces.md, eval/query-log.md, colony-state/log.md, fault-isolation/incident-log.md, protocol/changelog.md) MUST NOT be modified in place. Entries are appended. Existing entries are never edited or deleted.
The memory/ directory MUST contain exactly the regions defined in the node’s policy configuration (§5.2.1). The reference configuration defines five regions. A node configured with three regions (the protocol minimum) would have three subdirectories.
The glacier/index.md file MUST be updated whenever an entry is archived to glacier. An unindexed glacier entry is equivalent to a deleted entry — it violates CDR Theorem 1.

8.2 CLAUDE.md — The Protocol Core

CLAUDE.md is the agent’s operating constitution. Claude Code reads this file at session start, before any user interaction. It contains the protocol rules that the agent MUST follow — region definitions, decay rates, provenance requirements, the action cascade, and references to the slash commands that implement each operation path.

A conforming CLAUDE.md MUST include the following sections. The content below is the reference configuration — implementations MAY adjust policy parameters (§5) but MUST NOT omit protocol requirements.

## Identity

This workspace is an Synixolis-conforming memory node. All memory operations
follow the Synixolis protocol. Read `colony/manifest.md` for this node's
receptor, charter, scope, and current state.

## Memory Regions

Five metabolic regions with timescale-matched lifecycle:

| Region | Path | Timescale | Lifecycle |
|---|---|---|---|
| ephemeral | `memory/ephemeral/` | minutes–hours | Hard-expire at TTL. No decay. True deletion permitted. |
| operational | `memory/operational/` | days–weeks | Active decay (0.05/day). Renewal on positive evidence. Archive at confidence < 0.3. |
| structural | `memory/structural/` | months–quarters | Slow decay (0.01/day, applied weekly). Review-gated renewal. Archive at confidence < 0.2. |
| identity | `memory/identity/` | permanent | No decay. Human-gated modification only. Never archive without human approval. |
| glacier | `memory/glacier/` | indefinite | Cold storage. Indexed. Never deleted. Available via page-fault cascade on query miss. |

**Classification rule:** Assign entries by the information's natural timescale,
NOT by access frequency. An architecture decision accessed daily is structural.
A meeting action item accessed once is operational.

## Provenance (Non-Negotiable)

Every memory entry MUST carry:
- `source`: reference to the originating input (user message, tool output, or parent entry ID)
- `provenance`: ordered chain of citations terminating at a verifiable external source

Entries without provenance MUST be rejected. Circular provenance chains are a protocol violation.
Log all provenance violations to `fault-isolation/incident-log.md`.

## Operations

| Command | Operation Path | Reference |
|---|---|---|
| `/memory-write` | Write Path: ingest → classify → contradict → write → link | §3.3.1 |
| `/memory-review` | Maintenance Path: decay → renew → condense → archive → expire | §3.3.3 |
| `/reflect` | Condensation: observations → patterns → principles | §3.3.3 Stage 3 |
| `/query` | Read Path: query → retrieve (page-fault cascade) → log | §3.3.2 |
| `/status` | Health dashboard: region stats, decay status, colony state | — |
| `/evolve` | Evolution Path: trace → analyze → propose → evaluate → compile → demote | §3.3.4 |
| `/housekeeping` | Maintenance: link audit, expiry enforcement, archive pass | §3.3.3 |

## Action Cascade

When processing input, evaluate in this order (cheapest first):

1. **ROUTE** — Can another node handle this better? Check `colony/manifest.md` for affinities.
2. **PUSH** — Is this self-contained and ephemeral? Isolate in a scratch frame, process, discard.
3. **HANDLE** — Process with full memory operations (default).
4. **SPAWN** — Does scope drift exceed threshold? If lifecycle gates are satisfied, spawn a child.

## Telemetry

Log every decision, lifecycle event, memory operation, and fault to `eval/traces.md`.
Log every query outcome (HIT/MISS/PARTIAL) to `eval/query-log.md`.
Traces are append-only. Never modify existing trace entries.

## Maintenance Schedule

On session start: sync shared state, check fault notifications, run ephemeral expiry.
On session end: write heartbeat, flush traces, check condensation triggers.
Between interactions: run periodic tasks from `colony/maintenance-queue.md` within budget.
See `colony/maintenance-queue.md` for the full task queue.

## Fault Isolation

Run invariant checks on every write: schema validation, provenance chain validation, rate limits.
Invariant definitions: `fault-isolation/invariants.md`.
Log all fault events to `fault-isolation/incident-log.md`.
Fault response escalation: MONITOR → FENCE → ROLLBACK → EXCISE → RESET.
Fencing and monitoring are autonomous. Rollback and excision require human approval.
Reset always requires human approval.

## Convention Evolution

Compiled routing rules: `protocol/conventions.md`.
Immutable core rules: `protocol/hardwired.md`.
All changes logged to: `protocol/changelog.md`.
Compiled rules carry provenance and a review date. Rules past review date MUST be re-evaluated.

What CLAUDE.md Is and Is Not

CLAUDE.md IS:

The Level 3 (prompt-compiled) layer of the inference optimization path (§4). The rules in this file are loaded into the agent’s context at session start, at near-zero marginal inference cost.
The human-readable specification of protocol requirements and default policy values.
The static operating instructions — the agent reads them, it does not modify them. Convention evolution writes to protocol/conventions.md, not to CLAUDE.md.

CLAUDE.md IS NOT:

The complete protocol. Slash commands in .claude/commands/ contain the detailed operation logic. CLAUDE.md provides the frame; the commands provide the procedures.
A configuration file. Policy parameters that the system or human may change live in policy-specific files (see §5). CLAUDE.md contains the reference defaults for quick reference.
Modifiable by the agent. The agent MUST NOT write to CLAUDE.md during operation. Updates to CLAUDE.md are deployment-level changes (new protocol version).

8.3 Slash Commands

Each slash command maps to one or more operation paths defined in the node contract (§3). The commands are stored as markdown files in .claude/commands/ — Claude Code reads the file content as the command’s instruction set when the user invokes the command.

8.3.1 `/memory-write` — Write Path

Maps to: §3.3.1 (Write Path — ingest → classify → contradict → write → link)

Trigger: User invokes /memory-write with content to be stored, or the agent determines during normal interaction that information should be persisted.

Procedure:

When invoked, execute the full write pipeline on the provided content.

## Stage 1: Ingest
Decompose the input into discrete factual claims or observations.
Each claim becomes a candidate memory entry with `content` and `source` populated.
Source MUST reference the originating input (user message ID, tool output, or conversation turn).

## Stage 2: Classify
For each candidate, determine the metabolic region by information timescale:
- Minutes–hours → ephemeral (set TTL)
- Days–weeks → operational (set initial confidence: 0.8)
- Months–quarters → structural (set initial confidence: 0.9)
- Permanent → identity (requires explicit human confirmation before writing)

Check `protocol/conventions.md` for compiled classification rules first.
If a rule matches with confidence above its threshold, apply it (Level 2 optimization).
If no rule matches, classify by reasoning about the information's natural timescale (Level 0).
Log the classification decision to `eval/traces.md` with the method used (rule vs inference).

## Stage 3: Contradict
Search the target region for existing entries that semantically contradict the candidate.
- If contradiction found with higher-confidence existing entry: write the candidate anyway,
  but log the conflict to `eval/traces.md` and `fault-isolation/incident-log.md`.
- If contradiction found with lower-confidence existing entry: reduce the existing entry's
  confidence by the contradiction penalty (default: 0.2).

## Stage 4: Write
Validate the candidate against the entry schema:
- All required fields present (id, region, created, last_renewed, renewal_count,
  confidence, decay_rate, content, source, provenance, links)
- Provenance chain is acyclic and terminates at a verifiable source
- Confidence is within [0.0, 1.0]
- ID is unique across all regions including glacier

If validation fails: reject the entry, log to `fault-isolation/incident-log.md`, inform the user.
If validation passes: append the entry to the appropriate region file.

## Stage 5: Link
Identify related entries across all regions. Populate the `links` field.
Update the `links` fields of related entries symmetrically.

## Telemetry
Log a `memory:write` event to `eval/traces.md` for each entry written.
Log a `decision:classification` event with the region assignment rationale.

8.3.2 `/memory-review` — Maintenance Path

Maps to: §3.3.3 (Maintenance Path — decay → renew → condense → archive → expire)

Trigger: User invokes /memory-review, or the maintenance scheduler triggers a decay/renewal pass.

Procedure:

Execute the full maintenance pipeline across active memory regions.

## Stage 1: Decay
For each entry in `memory/operational/`:
  - Compute elapsed time since `last_renewed`
  - Reduce `confidence` by `decay_rate × elapsed_days`
  - Clamp confidence at 0.0

For each entry in `memory/structural/`:
  - Apply structural decay rate (default: 0.01/day, checked weekly)
  - Only apply if last decay pass was >= 7 days ago

Do NOT decay identity or glacier entries.

## Stage 2: Renew
Check `eval/query-log.md` for entries that were retrieved AND marked useful since last review.
For each such entry:
  - Increase confidence by renewal amount (operational: 0.3, structural: 0.2)
  - Clamp at 1.0
  - Update `last_renewed` to current timestamp
  - Increment `renewal_count`

## Stage 3: Condense
Check `memory/operational/observations.md` for observation clusters that meet promotion criteria:
  - 3+ observations in the same domain
  - Spanning at least 14 days
  - Average confidence >= 0.5

For qualifying clusters: draft a condensed structural entry, populate provenance
referencing all source observations, and present to user for review before writing
to `memory/structural/`.

## Stage 4: Archive
Move entries with confidence below archival threshold to `memory/glacier/`:
  - Operational entries below 0.3
  - Structural entries below 0.2

Retain all fields. Update `memory/glacier/index.md` with the archived entry's ID,
original region, and a content summary.
Log each archival as a `lifecycle:archive` event.

## Stage 5: Expire
Delete ephemeral entries past their TTL. This is the ONLY true deletion in the system.
Log each expiry as a `lifecycle:expire` event (entry ID and TTL, not content).

## Summary
After completing all stages, report:
  - Entries decayed (count, regions)
  - Entries renewed (count, reasons)
  - Entries condensed (count, from → to)
  - Entries archived (count, regions)
  - Entries expired (count)

8.3.3 `/reflect` — Condensation Pipeline

Maps to: §3.3.3 Stage 3 (Condense) — a focused invocation of the condensation stage only.

Trigger: User invokes /reflect to explicitly trigger observation-to-pattern promotion.

Procedure:

Scan `memory/operational/` for observation clusters ready for condensation.

## Step 1: Cluster Detection
Group observations by domain/topic. For each cluster:
  - Count: at least 3 observations required
  - Time span: observations must span at least 14 days
  - Confidence: average confidence must be >= 0.5

## Step 2: Pattern Extraction
For each qualifying cluster, synthesize a pattern:
  - What recurring theme or principle do these observations share?
  - What is the compressed claim that captures the cluster's essence?
  - Carry provenance: list all source observation IDs

## Step 3: Promotion
Draft the condensed entry for `memory/structural/` with:
  - Full entry schema fields
  - `source`: list of source observation entry IDs
  - `provenance`: chain from each source observation back to its original source
  - `confidence`: average of source observation confidences
  - `region`: structural

Present the draft to the user. Write only on confirmation.
Mark source observations for archival to glacier after successful promotion.

## Step 4: Log
Log a `decision:condensation` event to `eval/traces.md` for each promotion,
including the source observation count and the condensed content summary.

8.3.4 `/query` — Read Path

Maps to: §3.3.2 (Read Path — query → retrieve → log)

Trigger: User invokes /query with a search question, or the agent determines a memory lookup is needed during normal interaction.

Procedure:

Search memory using the page-fault cascade, with reads-as-writes logging.

## Stage 1: Query
Record the query in `eval/query-log.md` BEFORE retrieval begins.
Parse the query into search terms, filters, and scope.

## Stage 2: Retrieve (Page-Fault Cascade)
Search regions in order, fastest timescale first:
  1. `memory/ephemeral/`
  2. `memory/operational/`
  3. `memory/structural/`
  4. `memory/identity/`
  5. `memory/glacier/` (via `glacier/index.md`)

Stop at first sufficient result unless the query requests exhaustive search.
If all active regions miss, MUST check glacier before returning empty.

For colony nodes: after local cascade, check `colony-state/shared-structural/`
and `colony-state/shared-identity/`.

## Stage 3: Log (Reads-as-Writes)
Append to `eval/query-log.md`:
  - query: the original query text
  - result: HIT | MISS | PARTIAL
  - regions_searched: which regions were consulted
  - entries_accessed: entry IDs retrieved
  - entries_useful: entry IDs the user actually used (mark after interaction completes)
  - entries_missing: description of what was needed but not found (for MISS/PARTIAL)
  - timestamp

MISS results with `entries_missing` are the primary input for gap detection in `/evolve`.

8.3.5 `/status` — Health Dashboard

Maps to: No single contract operation. Aggregates state from all subsystems.

Trigger: User invokes /status to assess node health.

Procedure:

Report the current state of all node subsystems.

## Memory Regions
For each region, report:
  - Entry count
  - Average confidence
  - Entries approaching archival threshold (confidence within 0.1 of threshold)
  - Last decay pass timestamp
  - Oldest entry without renewal

## Eval Health
  - Total trace count
  - Query log: HIT/MISS/PARTIAL ratio over last 7 days
  - Compiled rules count + any past review date

## Maintenance Queue
  - Pending tasks (from `colony/maintenance-queue.md`)
  - Overdue tasks (due date in the past)
  - Deferred tasks (deferred_count > 0, flag any with count >= 3)

## Colony Status
  - Node state (INITIALIZING / ACTIVE / DORMANT / FENCED / TERMINATED)
  - Last heartbeat timestamp
  - Colony size (from colony-state if available)
  - Last shared state sync timestamp

## Fault Status
  - Active fences (if any)
  - Recent incidents (last 7 days from `fault-isolation/incident-log.md`)
  - Provenance audit: last run, next scheduled

## Warnings
  - Flag any region with 0 entries (possible bootstrap issue)
  - Flag any append-only file that appears to have been modified in place
  - Flag any maintenance task deferred 5+ times
  - Flag any compiled rule past its review date

8.3.6 `/evolve` — Evolution Path

Maps to: §3.3.4 (Evolution Path — trace → analyze → propose → evaluate → compile → demote)

Trigger: User invokes /evolve, or the maintenance scheduler triggers convention review.

Procedure:

Mine eval traces for stable patterns and manage the compiled rule lifecycle.

## Stage 1: Analyze Traces
Scan `eval/traces.md` and `eval/query-log.md` for patterns:
  - Stable classification mappings (source X always classified to region Y)
  - Consistent query misses (queries about topic Z always return MISS)
  - Recurring contradictions (entries from source A conflict with source B)
  - Stable routing decisions (inputs matching pattern P always get same treatment)

Only consider patterns with:
  - At least 50 supporting traces (configurable: policy `evolution.compilation_threshold.min_traces`)
  - At least 0.95 accuracy across traces (configurable: policy `evolution.compilation_threshold.min_accuracy`)

## Stage 2: Propose
For each qualifying pattern, draft a convention change:
  - The proposed rule (e.g., "source:meeting-transcript → region:operational")
  - The trace evidence (count, accuracy, time window)
  - Expected impact (which operations would change behavior)
  - Confidence score

## Stage 3: Evaluate
For each proposal, run counterfactual evaluation:
  - If this rule had been in effect during the evidence window,
    would classifications have improved?
  - Produce a quantified result (e.g., "47/50 correct, 3 mismatches")

## Stage 4: Compile or Demote
Proposals that pass evaluation: write to `protocol/conventions.md` with:
  - The rule
  - `compiled_from`: trace evidence reference
  - `review_date`: current date + rule_review_interval (default: 60 days)
  - `demotion_threshold`: accuracy below which the rule is demoted (default: 0.7)

Existing rules past their `review_date`: re-evaluate against recent traces.
  - Accuracy above demotion_threshold: renew (update review_date)
  - Accuracy below demotion_threshold: demote to Level 0 (remove from conventions,
    archive to `eval/compiled-rules.md` with full performance history)

Log all compilations as `eval:rule_compiled` events.
Log all demotions as `eval:rule_demoted` events.
Log all changes to `protocol/changelog.md`.

8.3.7 `/housekeeping` — Maintenance Operations

Maps to: §3.3.3 (Maintenance Path — subset: link audit, expiry, archive)

Trigger: User invokes /housekeeping for explicit maintenance, or the scheduler runs deferred tasks.

Procedure:

Run deferred and routine maintenance tasks.

## Link Audit
For each entry in `memory/operational/` and `memory/structural/`:
  - Verify all entries referenced in `links` still exist
  - Remove dangling references (target archived or expired)
  - Log broken links to `eval/traces.md`

## Expiry Enforcement
Delete all ephemeral entries past TTL.
Log each as `lifecycle:expire`.

## Archive Pass
Move entries below archival threshold to glacier:
  - Operational: confidence < 0.3
  - Structural: confidence < 0.2
Update `memory/glacier/index.md` for each.
Log each as `lifecycle:archive`.

## Maintenance Queue
Process pending tasks from `colony/maintenance-queue.md` in priority order.
Respect the maintenance budget (default: 15% of session inference budget).
Update `last_run` timestamps on completed tasks.
Increment `deferred_count` on tasks that cannot run within budget.
Flag tasks with `deferred_count >= 5` to the user.

## Summary
Report what was done: links repaired, entries expired, entries archived,
tasks completed, tasks deferred.

8.4 Node Bootstrap — How to Instantiate a Node

Bootstrap is the procedure that takes an empty directory and produces a conforming node in INITIALIZING state, then transitions it to ACTIVE. There are two bootstrap modes: standalone (new colony of size 1) and join (joining an existing colony).

8.4.1 Standalone Bootstrap

A standalone bootstrap creates a new node that is the sole member of a new colony.

Preconditions: An empty directory with write access. A Claude Code session.

Procedure:

Create directory structure. All directories and files listed in §8.1 MUST be created. Files MAY be initialized with empty content (except CLAUDE.md and colony/manifest.md).
Write CLAUDE.md. Copy the reference CLAUDE.md (§8.2) into the root. If human priors are provided (§5.3), adjust the policy parameters in CLAUDE.md accordingly.

Write manifest. Initialize colony/manifest.md with the node’s identity:

node:
  id: NODE-{generated-UUID-short}
  receptor: "{domain description — what this node specializes in}"
  charter: "{operating mandate — what this node does}"
  scope: "{boundary — what this node does NOT do}"
  state: INITIALIZING
  created: {ISO-8601}
  last_heartbeat: {ISO-8601}
  session_id: SESSION-{generated-UUID-short}
  colony_size: 1

Initialize fault isolation. Write fault-isolation/invariants.md with the hardwired validation rules:

invariants:
  - name: provenance_acyclicity
    check: "Provenance chain contains no cycles"
    on_violation: "Reject entry, log to incident-log.md"
    severity: FENCE

  - name: schema_conformance
    check: "All required entry fields present and valid"
    on_violation: "Reject entry, log to incident-log.md"
    severity: MONITOR

  - name: write_rate_limit
    check: "Writes per hour <= 100"
    on_violation: "Throttle writes, log to incident-log.md"
    severity: MONITOR

  - name: spawn_rate_limit
    check: "Spawns per day <= 5"
    on_violation: "Block spawn, log to incident-log.md"
    severity: FENCE

  - name: id_uniqueness
    check: "Entry ID is unique across all regions including glacier"
    on_violation: "Reject entry, log to incident-log.md"
    severity: MONITOR

Initialize protocol files. Write protocol/hardwired.md with the locked protocol requirements (§5.1). Write empty protocol/conventions.md and protocol/changelog.md.
Initialize colony state. For a standalone node, colony-state/log.md starts empty. No checkpoint is needed (there is no prior state to snapshot).
Initialize maintenance queue. Write colony/maintenance-queue.md with the default periodic tasks and their initial due dates set to the current timestamp (all tasks are due immediately on first session).
Write identity entries. If the human provides identity priors (mission, values, core preferences), write them to memory/identity/core.md with full entry schema fields and source: "human_prior".
Transition to ACTIVE. Update colony/manifest.md: set state: ACTIVE. Write a lifecycle:state_change event to eval/traces.md. Write the first heartbeat. The node is now operational.

Validation: After bootstrap, the user SHOULD invoke /status to verify:

All directories exist
Manifest is populated
CLAUDE.md is present
No fault conditions

8.4.2 Colony Join Bootstrap

A colony join bootstrap creates a new node that joins an existing colony. This occurs on SPAWN decisions (§3.4) — renewal spawn, specialization spawn, or delegation spawn.

Preconditions: An empty directory. A parent node or colony coordinator has prepared a state digest and a checkpoint reference.

Procedure:

Steps 1–5 from standalone bootstrap — create the directory structure, CLAUDE.md, manifest, fault isolation, and protocol files.
Load checkpoint. Copy the most recent checkpoint from the parent’s colony-state/checkpoints/ into the new node’s colony-state/checkpoints/. Materialize the shared views from the checkpoint.
Replay log tail. Fetch all log entries from the colony’s colony-state/log.md that have seq_id greater than the checkpoint’s seq_id. Apply them in causal order to update materialized views.
Load state digest. If the parent provided a compressed state digest (renewal spawn — max 512 tokens per §5.2.11), write the digest contents to the appropriate memory regions. Each digest entry carries provenance referencing the parent node and the source entries it was condensed from.
Register with colony. Append a PROMOTE entry to the colony’s colony-state/log.md announcing the new node. Set colony_size in the manifest.
Transition to ACTIVE. Same as standalone step 9.

8.5 Inter-Node Communication — Channel Types

Nodes in a colony communicate through typed message channels. The colony/channels/ directory contains one file per channel type. Each channel file is an append-only message log with structured entries.

Channel Architecture

Channels are a pub/sub mechanism. A node publishes a message by appending to the channel file. Other nodes read the channel file on session-start sync (or periodic sync during long sessions). There is no push notification — channel reads are pull-based, driven by the session lifecycle.

The channel transport is policy (§5). The reference implementation uses filesystem-based channels (markdown files in a shared directory or synchronized via git/filesystem sync). Alternative transports (MCP endpoints, message queues, HTTP) are conforming as long as they preserve the message schema and causal ordering.

Required Channel Types

A conforming colony MUST support the following channel types:

channels:

  OBSERVATION:
    purpose: Share raw observations that may be relevant to other nodes
    direction: any → any
    schema:
      sender: NODE-{id}
      timestamp: ISO-8601
      content: string                 # The observation
      domain: string                  # Topic domain (for routing/filtering)
      confidence: float
    processing: >
      Receiving node evaluates relevance to its receptor.
      If relevant: process through local write path.
      If not relevant: discard (no storage, but log receipt in traces).

  MEMORY_UPDATE:
    purpose: Notify colony that an entry has been promoted, archived, or modified
    direction: any → all
    schema:
      sender: NODE-{id}
      timestamp: ISO-8601
      entry_id: ENTRY-{id}
      operation: PROMOTE | ARCHIVE | EDIT | EXPIRE
      region: string
      summary: string                 # Brief content description (not full entry)
    processing: >
      Receiving node updates its local materialized views if the entry
      is in shared state. Local-only entries from other nodes are informational.

  CONVENTION_PROPOSAL:
    purpose: Propose a compiled rule for colony-wide adoption (§7 colony evolution)
    direction: proposing node → all
    schema:
      sender: NODE-{id}
      timestamp: ISO-8601
      rule: string                    # The proposed convention rule
      evidence:
        trace_count: integer
        accuracy: float
        time_window: string           # Evidence period
      impact: string                  # Which operations would change behavior
    processing: >
      Receiving nodes validate the proposal against their own traces.
      Each node responds with APPROVE or REJECT (appended to the same channel).
      N/2+1 approvals → rule is compiled into colony-wide conventions.

  FAULT_ALERT:
    purpose: Report detected faults for colony-level coordination (§7b)
    direction: detecting node → all
    schema:
      sender: NODE-{id}
      timestamp: ISO-8601
      target_node: NODE-{id}          # The node exhibiting the fault (may be self)
      severity: MONITOR | FENCE | ROLLBACK | EXCISE | RESET
      fault_type: string              # From fault taxonomy (§7b)
      evidence: string                # Supporting data
      recommended_action: string
    processing: >
      Colony evaluates the alert. If severity >= FENCE and corroborated by
      a second node, the target node is fenced. ROLLBACK and above require
      human approval.

  HEARTBEAT:
    purpose: Liveness assertion (§6c.2)
    direction: each node → colony
    schema:
      sender: NODE-{id}
      timestamp: ISO-8601
      state: ACTIVE | DORMANT | FENCED
      session_id: SESSION-{id}
    processing: >
      Colony-level liveness tracking. Nodes exceeding dormancy_threshold
      are classified DORMANT. Nodes exceeding liveness_threshold trigger
      liveness review.

  QUERY_ROUTE:
    purpose: Route a query to a node with higher affinity (action cascade ROUTE)
    direction: source node → target node
    schema:
      sender: NODE-{id}
      timestamp: ISO-8601
      target: NODE-{id}
      query: string
      routing_rationale: string       # Why this node was selected
    processing: >
      Target node processes the query through its local read path
      and returns results through a QUERY_RESPONSE on the same channel.

Channel Invariants

Channel messages MUST include sender and timestamp. Messages without sender identification are rejected.
Channel files are append-only. Messages are never edited or deleted.
A node MUST process all channel messages received since its last sync before handling new user interactions. Stale channel state can cause a node to operate on outdated colony information.
Channel processing MUST NOT block user interaction beyond the session-start sync window. If the channel backlog is large, the node MUST process FAULT_ALERT and HEARTBEAT messages first (they affect operational correctness), then process remaining channels asynchronously between user interactions.

8.6 Single-Node vs. Colony Deployment

The reference implementation supports both single-node (standalone) and colony (multi-node) deployments. The node contract is identical in both cases — the difference is which subsystems are active.

Single-Node Deployment

A single-node deployment is a degenerate colony of size 1. The node implements the full contract but several colony subsystems operate in trivial mode:

Subsystem	Single-Node Behavior
Action cascade	ROUTE is never triggered (no other nodes). SPAWN MAY be triggered if scope drift exceeds threshold.
Colony channels	`colony/channels/` exists but contains no messages. The node does not read or write channel files.
Shared state	`colony-state/log.md` exists but contains only the node’s own entries. Materialized views mirror local state.
Consensus	Not applicable. Promotions to shared state are unilateral (the node is the only voter).
Liveness detection	Heartbeat is written to manifest for protocol conformance, but no other node reads it.
Fault isolation	Fully operational. Self-monitoring detects local faults. Colony-level correlation is not available.
Maintenance scheduling	Fully operational. All periodic tasks run on schedule.

A single node MAY transition to a colony at any time by spawning a child node. When the first SPAWN occurs, the parent becomes a colony of size 2 and the colony subsystems activate.

Colony Deployment

A colony deployment consists of two or more nodes with:

A shared colony-state/ directory (synchronized via the configured transport — filesystem, git, MCP)
Active channel communication via colony/channels/
Consensus participation for shared state mutations
Cross-node fault detection and provenance auditing
Colony-level lifecycle management (spawn, cull, merge decisions)

What changes in colony mode:

Subsystem	Colony Behavior
Action cascade	ROUTE is evaluated on every input. Affinity comparison against colony manifest.
Colony channels	All channel types active. Messages processed on session-start and between interactions.
Shared state	Log receives entries from multiple nodes. Materialized views are eventually consistent across nodes (causally consistent per §6b).
Consensus	Required for shared state promotions. N/2+1 votes needed.
Liveness detection	Heartbeats from all nodes tracked. Dormancy and liveness thresholds enforced. Colony health checks run weekly.
Fault isolation	Full cross-node capability. Corroboration from a second node strengthens fault signals. Provenance audits sample shared entries.
Maintenance scheduling	Each node runs its own maintenance queue. Colony health check is a periodic task on every node.

What does NOT change: The node contract (§3), the memory entry format, the operation paths, the telemetry requirements, the protocol/policy distinction, the lifecycle gates, and the CLAUDE.md structure are identical for single-node and colony deployments. A conforming single node can join a colony without structural changes — it activates the colony subsystems and begins syncing shared state.

Migration Path

Single-node to colony migration:

The single node decides to SPAWN (action cascade or human directive).
The parent prepares a state digest for the child.
The parent creates a checkpoint of its current state → colony-state/checkpoints/.
The child bootstraps via colony join (§8.4.2).
Both nodes begin writing to shared channels and the colony log.
The parent’s next /status invocation shows colony_size: 2.

No data migration is required. No directory restructuring. The single-node directory structure already contains all the colony infrastructure — it was dormant, and now it activates.

8.7 `.claude/settings.json` — Permissions

The Claude Code settings file controls what tools and file paths the agent is permitted to access. A conforming node MUST have settings that grant:

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(memory/**)",
      "Write(eval/**)",
      "Write(colony/**)",
      "Write(colony-state/**)",
      "Write(fault-isolation/incident-log.md)",
      "Write(fault-isolation/fault-signatures.md)",
      "Write(fault-isolation/audit-schedule.md)",
      "Write(protocol/conventions.md)",
      "Write(protocol/changelog.md)"
    ],
    "deny": [
      "Write(CLAUDE.md)",
      "Write(protocol/hardwired.md)",
      "Write(fault-isolation/invariants.md)",
      "Write(.claude/**)"
    ]
  }
}

Permission Rationale

Permission	Rationale
`Read(*)`	The agent MUST be able to read all node state to perform queries, maintenance, and fault checks.
`Write(memory/**)`	The write, maintenance, and condensation paths require writing to all memory regions.
`Write(eval/**)`	Telemetry is append-only but requires write access.
`Write(colony/**)`	Manifest updates (heartbeat), channel messages, and maintenance queue updates require write access.
`Write(colony-state/**)`	Log appends, materialized view updates, and checkpoints require write access.
`Write(fault-isolation/incident-log.md)`	Fault events must be logged.
`Write(protocol/conventions.md)`	The evolution path writes compiled rules.
`Write(protocol/changelog.md)`	All convention changes must be logged.
`Deny Write(CLAUDE.md)`	The protocol core is not modifiable by the agent (§8.2).
`Deny Write(protocol/hardwired.md)`	Locked protocol requirements (§5.1) are immutable within a spec version.
`Deny Write(fault-isolation/invariants.md)`	Hardwired invariant checks are not modifiable by the agent.
`Deny Write(.claude/**)`	The agent MUST NOT modify its own command definitions or permissions.

Implementations MAY tighten permissions further (e.g., restricting Write(memory/identity/**) to require interactive confirmation). Implementations MUST NOT loosen the deny list — the denied paths enforce the protocol/policy boundary.

Reference Implementation

8.0 Preamble

Justification

Operating Timescale

Distributed Systems Framing

8.1 Directory Structure

Directory Semantics

Structural Invariants

8.2 CLAUDE.md — The Protocol Core

What CLAUDE.md Is and Is Not

8.3 Slash Commands

8.3.1 /memory-write — Write Path

8.3.2 /memory-review — Maintenance Path

8.3.3 /reflect — Condensation Pipeline

8.3.4 /query — Read Path

8.3.5 /status — Health Dashboard

8.3.6 /evolve — Evolution Path

8.3.7 /housekeeping — Maintenance Operations

8.4 Node Bootstrap — How to Instantiate a Node

8.4.1 Standalone Bootstrap

8.4.2 Colony Join Bootstrap

8.5 Inter-Node Communication — Channel Types

Channel Architecture

Required Channel Types

Channel Invariants

8.6 Single-Node vs. Colony Deployment

Single-Node Deployment

Colony Deployment

Migration Path

8.7 .claude/settings.json — Permissions

Permission Rationale

8.3.1 `/memory-write` — Write Path

8.3.2 `/memory-review` — Maintenance Path

8.3.3 `/reflect` — Condensation Pipeline

8.3.4 `/query` — Read Path

8.3.5 `/status` — Health Dashboard

8.3.6 `/evolve` — Evolution Path

8.3.7 `/housekeeping` — Maintenance Operations

8.7 `.claude/settings.json` — Permissions