The Great Library of SISO · Operating contract

Ecosystem Intelligence

The registry explains what exists. Ecosystem Intelligence explains what is moving, what changed, why it changed, which lane owns it, how it was verified, and where the next agent should continue.

Canonical split: immutable records under registry/events/ and registry/decisions/ are authoritative. /intelligence.json is the machine projection. /intelligence/ is one generated chronological reading surface. Git remains the audit trail.

What each layer answers

QuestionSource
What is this thing?Work
What exact version has evidence?Release
What is selected now?Snapshot
How do components operate together?Assembly
What is awaiting promotion?Source Inventory
What is happening, why, and who owns the lane?Event thread
Why was an architectural boundary chosen?Decision / ADR

Event threads

An Event is an immutable close-of-block record, not a transcript. It carries intent, reasoning, changes, registry scope, evidence, coordination, and next actions. A successor references one predecessor. The latest Event in the thread derives current state; old Events are never edited.

Live states are planned, active, and blocked. A live Event must name its branch and reserve machine-neutral repository paths. Validation rejects forks and overlapping reservations across active thread heads.

Agent lane protocol

  1. Read intelligence.json before opening a lane.
  2. Check active initiatives and reserved paths.
  3. Publish an immutable initiative_started Event on canonical main before parallel implementation begins.
  4. Work only inside the declared branch and scope. Never publish a local worktree path.
  5. Close the thread with a successor initiative_completed, initiative_blocked, or correction_recorded Event carrying exact evidence and handoff actions.
  6. Every new whole-Library Snapshot from V24 onward must appear in at least one Event.

Decisions are ADRs

A Decision records context, the chosen boundary, rationale, alternatives, consequences, scope, and evidence. Accepted Decisions must enter the Event graph. A later Decision supersedes an earlier one by reference; accepted history is not rewritten.

Automatic changelog

The intelligence generator merges every accepted Release and Snapshot into a chronological registry stream. Authored Events add the intent and reasoning that manifests cannot express. This combination gives broad change coverage without asking agents to duplicate registry metadata in prose.

Publication boundary

Events may include public branch names, stable IDs, repository URLs, public commits, and verification receipts. They must not contain machine paths, credentials, private topology, client details, personal memory, raw transcripts, or unpublished operational evidence.

Five-minute recovery test

  1. Read the highest numeric Snapshot.
  2. Read intelligence.json: active initiatives, latest Events, active Decisions, and recent registry changes.
  3. Open the relevant Work, Release, Snapshot, or source record linked by the Event.
  4. Resume only when the intended owner, reserved scope, last evidence, and next action are clear.