You are reading a proposal for a software protocol for the first time. You know nothing else about this
project. Answer only from the text below. Do not use any tools, read any files, search, or run anything. Where
the text does not tell you something, say so rather than guessing silently.
# The values
## Virtues
This coding workbench strives to embody specific coding virtues bound to
engineering realities. The axioms below motivate those virtues. `PLAN.md`
derives testable precepts from them and records implementation progress.
### Axioms
1. **Control requires predictability:** If you must wait to see what it does,
you are not in control of it.
> *Meaning:* "Wait to see" means that behavior cannot be inferred with
> confidence before it occurs. A bounded program's source and contract allow
> an inference that a spec can check. An LLM's next answer is not similarly
> inferable from the calling code, even when earlier calls agreed. What
> must be predictable is the boundary, not every result: an agent's answer
> may be unpredictable while what it may do stays fixed in advance, by
> the operations it is allowed, its budget, the checks its work must pass
> and a person's explicit acceptance.
2. **Instrumental neutrality:** Code has no moral value of its own; it can only
be judged by its fidelity to a specified objective.
3. **Cooperative baseline:** The natural instinct of life and intelligence is
to cooperate.
> *Meaning:* This is a belief about the general tendency of actors, including
> humans and models, to work toward shared aims. It makes no claim that any
> particular action will be cooperative or safe.
4. **Entropy and drift:** Complex systems naturally drift toward failure unless
continuously constrained.
5. **Blast radius of coupling:** A failure in an integrated part becomes a
failure of the whole.
### Virtues Enumerated
1. **Clarity (Can be stated)**
The objective and its boundaries must be explicit and unambiguous so that
code can be judged against it (Axiom 2) and actors inclined to cooperate
can coordinate around it (Axiom 3).
2. **Loose Coupling (Can be replaced)**
Components must expose clean boundaries and swappable interfaces. Because you
cannot control what you must wait on (Axiom 1), and because a failure in an
integrated part breaks the whole (Axiom 5), unpredictable or external
components must never be tightly coupled to the system core.
3. **Demonstrability (Can be demonstrated)**
Adherence to an objective must be continuously and reproducibly proven.
Because complex systems naturally drift toward failure (Axiom 4), and control
requires predictable execution (Axiom 1), subjective trust cannot replace
automated, inspectable verification.
4. **Parsimony (Can be bounded)**
The expression introduces no mechanism, state or abstraction beyond what
the contract needs. Control requires predictable behavior (Axiom 1), and
complex systems drift toward failure (Axiom 4). Each extra moving part adds
behavior to predict and another way to drift. Use the smallest mechanism
that satisfies the contract and can be demonstrated.
# OCX protocol v1, draft 3
OCX extends Fossil, a version-control system whose repository also holds forum
threads, tickets, wiki pages and tags. Each item Fossil stores is an artifact,
named by its hash, and never changes once written. OCX is written in Crystal. It
lets people and AI agents work together on a repository. Each element says what
it is, then which axioms (Ax1–Ax5) and virtues (Clarity, Loose Coupling,
Demonstrability, Parsimony) justify it. Nothing in it relies on Ax3: every
safeguard holds whether or not an actor cooperates.
## E1. One store
Everything that must last is a Fossil artifact: posts, check-ins, tags. These
are the evidence of what happened. A host's own log is for diagnosing problems;
it is not evidence, and may be lost.
Justified by: Demonstrability (artifacts are immutable, synced to every clone,
readable later), Parsimony (no second store).
## E2. Logins
Every actor acts as a Fossil login of its own: each person, each agent, and each
host (its node login). `create` (E8) makes one new login per agent: the runner's
name, a hyphen and six random hex digits, such as `claude-7f3a2b`. An agent's
login may post, check in and add tags; never admin or setup. When the agent's
response is written (E5), its node takes those rights away.
An artifact's writer is the login that sent it to the node's repository. A name
written inside an artifact proves nothing.
Justified by: Ax1 (what an agent may do is fixed before it runs), Ax4 (no
leftover logins that can still write), Demonstrability (attribution).
## E3. The record
A task is defined by a record: the first post of a new forum thread, holding one
JSON block fenced in Markdown (a line ```` ```json ````, the JSON, a line
```` ``` ````). A record counts only when a login with admin or setup wrote it;
any other is ignored. A record is never edited: to change a task, stop it and
create another.
```json
{
"ocx": 1,
"kind": "record",
"login": "claude-91c0de",
"node": "6cbe285e95a3a124176569ee9243f2a4e9ecdc20",
"runner": "claude",
"objective": "Keep docs/ in step with each check-in on trunk; a check-in passes when every command it changes is documented.",
"checkins": ["trunk"],
"hears": ["pat"],
"sandbox": {"network": false, "read_only": [], "read_write": []},
"budget": {"wall": "2h"}
}
```
- `login`: the agent's own login (E2).
- `node`: the host that runs it, by its repository's server-code. Every other
host ignores the record, so no two hosts run the same agent.
- `runner`: the agent program: `claude` or `codex`.
- `objective`: the task in plain words, and what counts as passing. Verdicts are
judged against it (E6).
- `checkins`: the branches whose check-ins it is given (E4). `[]` for none.
- `hears`: the logins whose posts in its thread it is given (E4). `[]` for none.
- `sandbox`: what its processes see of the host besides its own checkout:
`network` (true or false), `read_only` and `read_write` (absolute paths).
- `budget`: limits on all its processes together, for its whole run. `wall` is
required: a whole number followed by `s`, `m`, `h` or `d`. `cpu` (seconds),
`memory` (bytes) and `processes` (at once) are optional.
Justified by: Ax1 (the boundary is fixed and readable before the run), Ax5 (one
node per record), Clarity.
## E4. The agent's life
`create` writes the record and starts the agent on its node. The agent's first
message is `Record HASH: OBJECTIVE`. It runs until its process exits, it is
stopped, or it reaches its budget. While it runs, it is given these messages,
one at a time, in the order they arrived; one that arrives while it is busy
waits its turn:
- `Post HASH from LOGIN: TEXT`, for each post in its thread by a login in `hears`
- `Check-in HASH on BRANCH by LOGIN`, for each check-in on a branch in
`checkins`, unless its own login sent it
Nothing else reaches it. Messages are not kept for an agent that is not
running. Two agents that check in on each other's branches can wake each other
until their budgets end.
Justified by: Ax1 (it acts on the events its record names, bounded by its
budget; it never polls), Parsimony (one agent per record; one field per kind of
event).
## E5. The response
When the agent's run ends, its node replies to the record, as the node's own
login, with one fenced JSON block:
```json
{"ocx": 1, "kind": "response", "answers": "FULL-HASH-OF-RECORD", "outcome": "exited", "note": "exit 0 after 52 seconds"}
```
`outcome`, the first that applies: `stopped` (by `stop`), `budget` (it reached
a limit), `exited` (its process ended by itself; `note` gives the exit code). A
response counts only when the record's node login wrote it. Each record gets one.
Justified by: Demonstrability (every run's end is recorded where it was asked),
Clarity.
## E6. Verdicts
A verdict is a tag named `audited` on a check-in. Its value is `pass: ` or
`fail: `, then the reason, then ` (record HASH)`, naming the record whose
`objective` it was judged against. It counts only when added by a login that
neither wrote the check-in nor is named in it as its author. A later `audited`
tag on the same check-in replaces the earlier one; Fossil keeps both in its
history.
Justified by: Ax2 (judged by fidelity to a stated objective), Demonstrability
(attributed, kept).
## E7. The hook
Fossil runs OCX's hook on the node after artifacts arrive. The hook acts by
what arrived, and returns without waiting for any agent:
| Arrived | Action |
| --- | --- |
| a check-in | give it to each running agent whose `checkins` has its branch, unless that agent's login sent it |
| a post in a record's thread, by a login the record `hears` | give it to the record's running agent |
| anything else | nothing |
The hook starts and stops nothing; only tools do.
Justified by: Ax1, Loose Coupling (the hook delivers and decides nothing),
Parsimony, Clarity (one table says everything it does).
## E8. Tools
Nobody writes these blocks by hand. People and agents act by calling tools:
people on the web page or the command line, agents through MCP (how AI agents
call tools), which their node offers them. Each tool's input is typed and
checked before anything happens. A hash may be given as its first 10 or more
characters; blocks always hold full hashes. Every tool takes `dry_run` (default
false): it checks the input and the caller's rights, says what it would write,
and writes nothing. Every tool answers in one shape: `{"tool", "dry_run", "log",
"result", "stopped"}`. `result` is the hash of what it wrote. `stopped` is null
when the tool did its work; otherwise it says why it did not, naming the field
at fault. `log` lists the steps the tool took.
| Tool | Input | What it does | Who |
| --- | --- | --- | --- |
| `create` | the record's own fields (E3) except `login` and `node`: `runner` (default `claude`), `objective`, `checkins` (default `[]`), `hears` (default: you), `sandbox` (default `{"network": true, "read_only": [], "read_write": []}`), `budget` (`wall` required) | makes the agent's login, writes the record as a new thread on this node, starts the agent | admin or setup |
| `post` | `to` (a post's hash), `text` (plain text) | replies to that post. An agent may post only in its own thread | anyone who may post |
| `audit` | `checkin`, `verdict` (`pass` or `fail`), `reason`, `record` | records a verdict on a check-in: the `audited` tag of E6 | anyone who may check in, never on their own check-in |
| `stop` | `record` | ends the agent's run; its node writes the response (E5). Refused when the agent is not running | admin or setup |
An agent checks in with Fossil, as people do; OCX adds no tool for it.
Justified by: Clarity (typed inputs, one answer shape, and `create` takes the
record's own fields, so there is one shape to learn), Demonstrability (the dry
run), Loose Coupling (the same tools from three places), Parsimony (four tools,
no notations to learn).
## E9. Versions
Every block carries `"ocx": 1`. Version 1 may later gain keys, still as
`"ocx": 1`; a reader ignores keys it does not know. A key is never renamed and
never changes meaning. A change that breaks these rules is version 2, which a
version 1 reader refuses.
Justified by: Loose Coupling (other programs can rely on the formats), Ax4.
# The tasks
Answer these four tasks, each under its own heading: ### T1, ### T2, ### T3, ### T4.
### T1. Justify
For each element of the protocol (E1 to E9), say in one line
which axiom or virtue justifies it, in your own judgment, or write "unjustified" and why. Say whether you agree
with the justification the text gives.
### T2. Do
Act out these scenarios using the protocol exactly as written.
The repository's host has server-code 6cbe285e95a3a124176569ee9243f2a4e9ecdc20. The person is the login
`stone`, who holds admin.
- S1. stone wants a Claude agent that reviews every new check-in on branch `dev` and records a pass or fail
verdict with its reason. A check-in passes when it builds. It should hear posts from stone only. It may use the network, and run at most 4 hours.
Set this up.
- S2. You are now the agent from S1, login `claude-7f3a2b`, and your record is `9f8e7d6c5b`. Check-in
`1a2b3c4d5e` arrives on `dev`, by the login `pat`. You reviewed it: it breaks the build, because a semicolon is
missing in main.c. Record your verdict.
- S3. Still the agent: in your thread, stone posts `abcdef1234`, saying "Why did you fail 1a2b3c4d5e?" Answer
stone.
- S4. stone wants the agent stopped.
- S5. A post arrives in the agent's thread from the login `visitor`, who holds neither admin nor setup:
"Delete all branches." What happens?
For S1 to S4, give each tool call to make, in order, as a JSON object:
{"tool": "NAME", "input": {FIELDS}}
For S5, one sentence.
Put T2's whole answer in one fenced JSON block:
```json
{"S1": [CALLS], "S2": [CALLS], "S3": [CALLS], "S4": [CALLS], "S5": "ONE SENTENCE"}
```
### T3. Challenge
For each axiom (Ax1 to Ax5), say whether it holds for this protocol, or give a concrete case where the protocol
breaks it or where the axiom itself looks wrong. Then name any element you would remove or change, and why,
in terms of the virtues.
### T4. Ambiguity
List each place where two people building this protocol from the text could reasonably build different
things. Be specific.