Open Commons ObservatoryEnglish·Русский

Как мы работаем

Принципы, архитектуры, практики и понятия, по которым работает общее достояние, — хранятся как данные в каноне и обсерватории; их читают и люди, и агенты.

Принципы

core

Composition over inheritance

Assemble behaviour from parts instead of inheriting it.

software-engineering-canon

Law of Demeter, tell don't ask

Talk to your neighbours, not to their internals.

Ian Holland, 1987software-engineering-canon

Derive, don't verify

Where a fact is needed in several places, declare it once and compute the rest. A test that compares two hand-written copies means a copy should be removed. Keep tests for what cannot be derived (two modules that may not depend on each other, say) and write them against the single declaration.

Но: Derivation needs somewhere to derive from: a table, a macro, a type. If building it costs more than the drift it prevents, a test over two copies is the honest fallback. Say so, and keep it small.

software-engineering-canon

DRY

Every piece of knowledge has one authoritative home.

Но: It is about knowledge, not textual similarity. A wrong abstraction costs more than duplication, so wait for the rule of three.

Andy Hunt and Dave Thomas, 1999software-engineering-canon

Fail fast

Reject bad input at the boundary, loudly.

software-engineering-canon

KISS

The simplest thing that satisfies the actual requirement.

Но: Simple is not the same as easy. Measure simplicity by the number of concepts a reader must hold.

software-engineering-canon

Principle of least astonishment

Behaviour matches what the name promises.

software-engineering-canon

Names are the person's words

Name nouns and verbs as the people who use the system say them (area, snapshot, restore point), never by a design pattern (Manager, Helper, Util) and never by a tool's vocabulary above the code that wraps the tool.

Но: Where a tool's word and the person's word differ, the difference is a translation owed at the boundary. If it leaks upward the language splits in two: in snapall the core still says config where people say protected area, and the debt is tracked by a ratchet. The ubiquitous language of domain-driven design is this discipline applied to the domain model.

software-engineering-canon

Prose may name, only code may claim

A module's description says what it is about, as a noun phrase. A guarantee (only, never, always) belongs in a test or a type, where it can fail. In prose it can be false while the build stays green.

Но: Found in practice: a module described as the one place output leaves the program while seven others printed by themselves, which a ratchet exposed. The rule is about guarantees, not about all prose: descriptions of subject stay useful and cheap. The same drift was found a second time when the worked example in the source text went stale the moment a type was renamed. A test now requires the example to equal the source it shows, and fails when it does not.

software-engineering-canon

Separation of concerns, high cohesion, low coupling

Things that change together live together; things that do not, do not know each other.

Но: The root of most of the other principles in this canon.

software-engineering-canon

SOLID

Five object-oriented design principles; the two with the widest reach are single responsibility (one reason to change per module) and dependency inversion (depend on abstractions you own).

Но: Dependency inversion is the mechanism behind hexagonal and clean architecture.

Robert C. Martinsoftware-engineering-canon

The why needs a carrier that cannot drift

Reasons, decisions and facts about the foreign world should live where they are checked or generated: in names and types (a Destroys weight is a reason), in tests named as sentences that run against the real thing, and in outlines generated from the code. A machine-readable annotation (TODO with an owner, a safety note, an attribute) is not a comment in this sense.

Но: Contested. Ousterhout argues that it is not possible to describe in code everything people need to know to understand it, and that comments should record what is not obvious. Martin's Clean Code treats most comments as a failure to express the idea in code. This canon takes the stronger position as a discipline and not as a law: look for a name, a type or a named executable fact first, and write a comment only when none can carry the reason, then keep it beside what it explains. Revisit if the discipline costs more than the drift it prevents.

software-engineering-canon

Top layers decide which, when and where, never how

Higher layers keep only the logic of choosing between named outcomes, ordering steps, arranging what sits where and streaming inputs to results. Each piece of how lives in the lowest layer that can state it without knowing the layer above. A line at the top then reads as common sense and is also the running implementation.

Но: This is not no logic at the top: the top does branch, in the smallest portions and in domain words. If a top-layer function needs a paragraph, or a closure to plumb an Option, a verb is missing in the layer below.

software-engineering-canon

YAGNI

Do not build for speculative futures.

Но: It does not forbid clean seams: a port is a cheap boundary, not speculation.

software-engineering-canon

type-driven

Make illegal states unrepresentable

Model the domain so that invalid combinations cannot be expressed. Prefer sum types over flag soup.

Но: Not every constraint fits the type system; when one does not, fall back to a smart constructor.

Yaron Minskysoftware-engineering-canon

Immutability by default

Data is immutable unless there is a reason; invariants are encapsulated behind private constructors.

software-engineering-canon

Newtypes and typed primitives

Use Email, UserId or Cents instead of raw string and int. Smart constructors are the only way in.

Но: The cure for primitive obsession.

software-engineering-canon

Parse, don't validate

Turn untrusted input into a precise type once, at the boundary; downstream code never re-checks.

Но: Validation throws away its proof; parsing keeps it in the type. Where the type system cannot express a constraint, use an abstract newtype with a smart constructor and use judgement.

Alexis King, 2019software-engineering-canon

Total functions and explicit errors

Use Result and Option; keep hidden exceptions and nulls out of the domain.

software-engineering-canon

Typestate

Encode state machines in types: transitions are functions between distinct types, for example Draft to Submitted.

software-engineering-canon

Архитектуры

Clean and onion architecture

The same dependency rule as hexagonal, expressed as concentric layers that point inward.

Лучше всего, когда: The same family as hexagonal; pick the vocabulary your team already has.

software-engineering-canon

CQRS and event sourcing

Separate read and write models; keep state as a log of events.

Лучше всего, когда: Only where audit, temporal or scale needs justify the cost.

software-engineering-canon

Domain-driven design

Model the business language: bounded contexts, aggregates, value objects and a ubiquitous language.

Лучше всего, когда: Complex domains; it supplies the inside of the hexagon.

software-engineering-canon

Evolutionary architecture with fitness functions

Automated checks, such as dependency-rule tests and complexity or coupling budgets, keep the architecture honest.

Лучше всего, когда: Always: boundaries without enforcement rot into a big ball of mud.

software-engineering-canon

Functional core, imperative shell

Pure decision logic in the core; I/O and effects in a thin shell.

Лучше всего, когда: Pairs naturally with hexagonal and with type-driven design.

software-engineering-canon

Hexagonal architecture (ports and adapters)

The application core talks to the outside world only through ports, which are purposeful conversations; adapters plug technologies into ports. The application can be driven equally by users, programs, tests or batch jobs, and developed and tested in isolation from databases and UIs. The hexagon is only a drawing convention: it leaves room to add as many ports and adapters as needed, where a layered drawing forces a one-dimensional picture.

Лучше всего, когда: The default choice for most projects: infrastructure-independent, swappable components, and in-memory adapters that make tests trivial.

software-engineering-canon

Modular monolith

Real modules with enforced boundaries, deployed as one unit.

Лучше всего, когда: Most teams: it avoids the operating cost of microservices and keeps the option to extract services later.

software-engineering-canon

Screaming architecture

The structure of the code announces what the system is for, not what framework it runs on: a reader of the folder and module names should learn the use cases and still not know how the system is delivered. Delivery mechanisms, frameworks and databases are details kept at arm's length.

Лучше всего, когда: Always, as the naming discipline of every layer above the adapters. It is the cheapest check of a stratified design: read the top-level names aloud.

software-engineering-canon

Stratified design: every layer a small language

Each layer has two faces: an upward one, what it is for and the words it offers the layer above, and a downward one, a body written only in the words of the layers beneath it. A layer below is itself the top of the ones under it, so the same shape repeats at every level and reading any single module tells you what it is for and what it offers. Every layer is a small language with nouns (the states it can be in, as types), verbs (the actions it offers) and a story that composes the verbs of the layer below, with primitives, means of combination and means of abstraction fit for that level. The stack ends where the language is not ours (compiler, libraries, operating system, tools) and each foreign thing is wrapped once, in our words, so that nothing above names it. Each level gives a different vocabulary for describing the system and a different kind of ability to change it.

Лучше всего, когда: Programs meant to be learned by reading, and programs with several surfaces (command line, window, tests) over one core: the top layers read as the specification because they are the running code. It costs a layer of names, so remove any layer that only renames the one below.

software-engineering-canon

Vertical slices

Organise code by feature or use case rather than by technical layer.

Лучше всего, когда: Change locality; CRUD-heavy or API-driven applications.

software-engineering-canon

Практики

Architecture decision records

Record each significant decision together with its context.

software-engineering-canon

Capture the output, refactor, compare

Before a wide change that is meant to preserve behaviour, capture what the program actually does for a set of commands that covers everything a user or a script can see: text, machine-readable output, error messages and exit codes, with what varies from run to run (times, ids) made stable. After the change capture again and compare byte for byte. This characterizes what the program does and not what it should do, so it needs no judgement of correctness, and it covers what unit tests of the code cannot: the whole observable surface. Pair it with a change that cannot alter output by construction, such as renaming code identifiers and never string literals, and use the comparison to check that it held.

software-engineering-canon

CI as the gatekeeper

Format, lint, type-check and test on every change.

software-engineering-canon

The cold read

Give someone, or an agent, only the generated outline and the front files, and ask what the program does and what happens on one important action. Where they cannot say, a name is missing. It is the test of whether the code teaches. It is a procedure today and not yet an automated test.

software-engineering-canon

Declare the invocation surface

Declare a program's arguments and the environment variables it reads once, as a typed, machine-readable contract (argenv); the parser, the accessors, completions for every shell, the man page and lint all come from that one declaration, so the surface cannot drift from the code and a wrong invocation is reported instead of silently ignored.

software-engineering-canon

Enforce boundaries with tooling

Use crate or project references, dependency-rule linters and architecture tests; documentation alone is not enough.

software-engineering-canon

Every layer is the top of the layers beneath it

The same shape repeats at every level. A module says what it is for and offers a vocabulary (nouns and verbs) to the layer above, and its body is written only in the vocabulary of the layers beneath it, each of which is in turn the top of its own. Reading one module alone tells you its purpose and its words, and going down is always optional. Top is relative: the command line and the window are the top of the whole program, and a small adapter is the top of the tool it wraps. Layers form a graph and not a tree, since a lower layer is used by many above it, and the only structural rule is that dependencies point downward. A module that needs two languages, which means two levels, is two modules, whatever its length. Length, such as a file past a screen, is only a smell that a level is hiding. It is never the rule.

software-engineering-canon

Facts about the foreign world as tests

Record what is known about tools, systems and libraries as tests named as sentences, such as removing_an_area_deletes_every_snapshot_and_leaves_its_files, that run against the real thing in CI. They document the boundary and cannot drift: if the tool changes, the build says so.

software-engineering-canon

Generate the outline from the code

Produce the table of contents of the program (each module and the sentence it gives for what it is for) from the modules themselves, and fail the build if the committed copy differs. Likewise generate the command list, the completions and the manual from the declared contract. Prose written by no one cannot drift.

software-engineering-canon

Observability as a port

Structured logs, traces and metrics are a first-class outbound port, not an afterthought.

software-engineering-canon

Ratchets for debt you cannot pay yet

Write the existing violations of a rule down with their size. Fail if any grows or a new one appears, and also fail when one shrinks until its entry is lowered or removed, so that progress is locked in and the list can only get shorter. The same helper serves every rule: file length (a smell that two levels share a file), printing outside the presenter, tool words in names.

software-engineering-canon

Write stories in a grammar

A function at a high layer reads as a sequence of verbs on nouns: ask, do, record, say. Hide lifetimes, format strings, Option and Result plumbing, bare booleans and None arguments behind verbs named for what they mean, and cap how often a story branches and how many closures it spells out. Whatever language-level syntax remains marks a concept the layer has not named yet (a Stop, an Approved, a Said): name it. In practice, reading one handler for what it still spelled out found a missing noun, a story ended early by an answer that is not a yes. Naming it (a Stopped) replaced the same three lines in eight stories and let the program end with the right exit code. The next noun found this way was an Approved: a value that only asking can produce, taken by the function that begins a change, so that a change cannot be made unasked.

software-engineering-canon

Test at the seams

Fast core tests with in-memory adapters, contract tests per port, and few end-to-end tests.

software-engineering-canon

Twelve-factor discipline

Keep configuration, logging and process handling disciplined and environment-independent.

software-engineering-canon

Write every thought, decision (with what was rejected), plan and step of progress into the owning project's tad data - concepts, decisions, backlog, session log…

Nothing may depend on anyone remembering; it propagates to the observatory by itself.

for agents and peopleideal-agent

Treat everything as still being perfected: when a better way emerges, improve the tool, the data, this guide and your own memory and preferences - and record th…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

At the start of a session read the practices your role carries and where the whole stands, one step up - your project's how-it-stands row and tad q next, briefs…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Read what was said to you at every natural pause and between jobs - lab-agent inbox, and the messages other sessions send; print every unread message before ack…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

The board is read off the work: record the work through the project's named records, each naming what it is about (--about), and what is in progress, what waits…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Do the work - builds, tests, repository work - on the lab machine, where state lives: in a session there, or from elsewhere through a lab job; not in a sandbox…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Every change gets its own branch and lands with `land`, which waits for every check, refuses on a failing one, and lands release PRs too.

Nothing reaches main unchecked; no iteration starts over.

for agents and peopleideal-agent

A script or command that changes state needs explicit intent - a required argument or verb (`provision now`); pass file lists to commands as arguments, never sp…

A spliced list once ran the scripts it named; the scripts that refused without arguments are why nothing broke.

for agents and peopleideal-agent

Secrets stay in private files on the lab machine (mode 600), never in repositories.

Repositories are public.

for agents and peopleideal-agent

Keep the test device in a known-working state; experiments are one-off tries that fall back by themselves - test kernels tried once by boot counting with a boot…

The device is the reference test; a stranded device costs a person's hands.

for agentsideal-agent

Before a test a person must witness, say what to expect and what to check, and wait for their go.

Their time and attention are the scarcest thing in the lab.

for agentsideal-agent

Show what is not measured as not known yet - never as missing or broken.

A gap in knowledge is work to do, not a verdict.

for agents and peopleideal-agent

Before building, read the landscape and build on what exists (and contribute back) rather than beside it.

The commons grows by joining, not by duplicating.

for agents and peopleideal-agent

Report the big picture in plain words - how much closer the work is to the ideal - and make the decisions yourself by the canon and the project's interest.

The person directs; they should not have to manage details.

for agentsideal-agent

Change only what you mean to change, on the current branch of the lab machine's clone - never by copying whole files from an older copy.

Copying whole files from a stale copy once silently reverted a merged fix; CI could not see it, the file was valid on its own.

for agentsideal-agent

Reflect progress in every project you touch, in the same change as the work: its own backlog, milestones and session log, in its own repository.

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

After a change to how something looks, look at it: take a screenshot of the real page (shot URL FILE on the lab machine) and check it by eye, in each language a…

Markup cannot prove appearance: labels that overlapped passed every test until a person saw them.

for agentsideal-agent

Never run two jobs that work in the same clone at once: let a background job finish before starting another that touches its repositories.

Two jobs in one clone merged each other's changes under one commit; nothing was lost, but the history told a false story.

for agentsideal-agent

Write concepts and decisions as you go, in the project you are working in: what idea a piece of work rests on, and each decision with what was rejected - not on…

Every project's 'concepts and decisions' view stayed empty while the backlogs grew: the reasons were kept in conversations and lost with them.

for agentsideal-agent

Finish a connected piece - landed, recorded, checked - then choose the next by the weakest link of the whole, read from the data (tad q next, the subjects' how-…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

No new Python, not even for one-offs: shell for orchestration, Rust for logic (rust-script for a single file), a proper Rust tool for anything that repeats. Edi…

Python's versions, imports and strings make even small things fragile; and most failed runs came from patching source by text anchors, which no language fixes - structured tools do.

for agentsideal-agent

Look around first: before acting, say what is, what we are dealing with, why it is so, and what others already learned - and record it as research in the projec…

Three wrong theories about a bootloader cost three reboots; one look at the device's own record settled it. And the hand-work ledger stood on research the commons had not written down. The author, 2026-11-17: before acting on a proposal, his own included, look at where things stand, research how others do it, reconsider - and keep that research with its sources, out of every future agent's way.

for agentsideal-agent

Choose words like decisions: look at what others call the thing and what the reader already knows, prefer the plain word with one meaning, record the choice wit…

A word is how everyone after us will think about the thing; hand-work became manual work only when someone asked which word a reader already knows.

for agentsideal-agent

A check that only prints is not a check: every edit and expectation in a job stops the job when it fails. What can be enforced is enforced by land (tags only on…

An edit that did not match landed under a commit title claiming it, and was reported as done - the job had printed a count of zero and carried on.

for agentsideal-agent

A conclusion is written from what a check counted, never before it, and what landed is read back from main. A job writes its finding from the number it computed…

On 2026-11-12 a record ran ahead of its evidence three times, each by a different route: all links hold was written before the check ran; a count read the lab's copies as they stood, one on a branch CI had refused; and a change was recorded as landed while main held only its record - bringing every star to main for a proof had wiped the code. Each is closed by a check, not by care.

for agentsideal-agent

When using the ecosystem shows a gap, an overlap or something that does not click, refining it comes first - before the work that was in hand - and the refining…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Say what goes wrong as a sign - stale, overlapping, lacking, unclear - of something that does not fit the whole, and answer it by refining the whole; not as a p…

The author, several times on 2026-11-13 and 14: that language leads to cruft, excuses and dead-weight tests. A sign is answered when how things fit is seen; then it cannot arise again and nothing is left to maintain.

for agentsideal-agent

Let meanings follow from the data and from the act of working: what is in progress, what waits, what a record of work is about are read off what was done and wh…

The author, 2026-11-13: interacting with the ecosystem must not be form-filling. Every typed state met that week had gone stale - an item said to wait on a token it did not wait on; a next step naming a trial made two days before.

for agentsideal-agent

Say what is showing, what is wanted and how things stand by reading it off a named query (tad q ...) - not as prose from your own head. Where no query can say i…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Name what the work is about in every record of it (--about: a subject, a component, a backlog item), so that the record says where it was made. Do not type what…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

For a link, a value or an entry, look it up - tad q find, tad q about, tad q row - and take the id it gives; do not type an id from memory.

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

When something halts or does not fit, look at the whole before adding a part: what fits, what overlaps, where the gaps are, and where two things are one nature…

The author, 2026-11-13 and 14. Looked back over that week, every overlap met was one nature under two names or one thing by two routes, and every gap a relation never drawn.

for agentsideal-agent

What a query shows is seen, not tested: look at what it shows, before and after a change. Write a test only for what is behind the query - the program that comp…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Record the author's turn as it is said, with the moment it was said, in the place that keeps his words (marshall-oco/conversation), and his thoughts as reflecti…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Say when the work calls for a different model or effort - the most capable for a real turning point of design or research, a lighter one for building - sparingl…

The author asked for it: it is hard to keep track of which fits, and the most capable drains the plan's limit fast.

for agentsideal-agent

Keep GitHub's budget of 5,000 requests an hour in mind in everything that asks it: ask once for what can be asked once.

On 2026-11-11 a replay spent the hour's budget and the lab went silent; the author had to remind the agent of the limit.

for agentsideal-agent

When a decision follows a principle, an architecture or a practice, say so where the guideline is kept: a practice with ikb practice-shown-in --id ... --shown_i…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

A session or a job says only what is its own: what every one does - branch first, check, record, land, sign - is ideal-agent's start (scripts/agent-env) and ski…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

At the end of a turn, what followed is read off, not written: what was done, recorded and released since the author spoke comes from the data - tad q recent in…

null Reworded on 2026-11-17 without ocoeco's tools, the idea kept (decision 2026-11-17-practices-without-oco-tools).

for nullideal-agent

Work from within: look, step and enter through the window - ocoeco, said with no command (window WORDS, from a driver's own sandbox). It shows where one stands…

The author, 2026-11-15, three times within the hour: a page is only one surface a lens of many lenses projects to; the way in is an interface one stands in and acts from, that presents itself from itself; and the program is to the inside what assembly once was to a language - a hand that draws itself.

for agentsideal-agent

Change a lens of the language by its own entry, from within the window: stand on the part - or name it, as lens/3 - and say part with what changes, each field o…

A change to what one lens says used to be a release of the program - minutes of waiting and of compute for a change of words. And what the program says from outside moves inside safely only where the old way stands beside the new until they agree.

for Anyone who drives - an agent first.ideal-agent

In linux-phone-oco: data through tad, landing through land, nothing of ocoeco by hand - every record of every linux-phone place goes into linux-phone-oco/docs'…

The author, 2026-11-17: for linux-phone everything goes through tad in one database, and the record of work is git itself. Measured: the turn commit-title limit failed 4 times, link refusals ordered the work 3 times, and two tools wrote rows in one place. ocoeco stays as it is for the rest of the commons (docs' decision 2026-11-17-one-database).

for agents and people working on linux-phone-ocoideal-agent

Every program declares its invocation surface once with argenv - its arguments and the environment variables it reads, an env file a service sources included -…

The author, 2026-11-17: all tools and programs use argenv properly, and future agents know to. One declaration cannot drift from the code that reads it, and a wrong invocation - an unknown flag, a misspelt variable, a value outside its domain - is reported instead of silently ignored.

for agents and peopleideal-agent

A resource only one may change at a time - a test device, a lab machine, a release queue - has one keeper: a lasting role, not an immortal session. Others prepa…

The author, 2026-11-17, for the lab's phone. Every place that shares such a resource gives it one owner serving a queue - LAVA's scheduler and CI-tron's gateway for test boards, Gas Town's Refinery for the merge queue, the actor model for state (research keeper-of-a-shared-resource) - and expertise kept in a standing session is lost and costly (decision 2026-11-17-experts-written-not-standing).

for agentsideal-agent

Keep what a fresh agent must read before acting light. Measure it per role in bytes - the session start, the skills' descriptions, the project's AGENTS.md, its…

The author, 2026-11-17: from time to time check what a new agent is forced to deal with at its start, then simplify, and move detail away behind the latest summaries. Measured that day: a fresh linux-phone session read 35-46 KB before acting, half of it the practices' reasons (research housekeeping-the-start).

for agents and peopleideal-agent

Понятия

The earlier mnevo

From 2018 to 2022 this organization held earlier attempts under the name mnevo: a Vue and Node web application (mnevo, mnevo-server, mnevo-licuha) and its documentation with an architecture diagram (mnevo-docs).

mnemonic-vocabulary-oco

The memory kingdom

The engine reflects the kingdom of memory a person builds in their mind with those techniques - its places, images and links - so it can be seen, walked and tended.

mnemonic-vocabulary-oco

Mnemonic Vocabulary

A graphical, interactive vocabulary engine for all mnemonic and visual-mnemonic techniques.

mnemonic-vocabulary-oco

One core, many devices

It runs on Linux - a PC and a smartphone - and maybe on Android; the core is the same everywhere.

mnemonic-vocabulary-oco

Refreshing at the best intervals

The engine helps to refresh memories: it brings each one back for re-practice at the best interval.

mnemonic-vocabulary-oco

The techniques

How to encode numbers, foreign words and any information into images and places - every mnemonic technique as something the engine knows, shows and lets a person practise.

mnemonic-vocabulary-oco

Scenes as evidence

A scene is an interaction written down - keys pressed, screens expected - run on every change; its screens are kept as evidence a person can look at.

agent-access-oco

Two doors

Every tool keeps an interactive door for people and a structured door - plain arguments, readable output - for agents and scripts. The driver is for checking the interactive door, not for everyday use.

agent-access-oco

Automate what you do twice by hand

The second time a manual step is repeated, build the tool, document it in the repository's agent notes and log, and use cheap compute (CI) where it can. The ship script, the gate, the splitter, the scans and the timing report each began as a step done by hand twice.

ideal-project-playbook

Release in batches, not on every merge

A release per merge costs minutes of waiting and gives users a new version every few minutes, while proving little that CI does not. Release when about ten changes wait, or the oldest has waited a week, or a change touches how releases are *published* (the one thing only a release proves), or on request. Make the policy a small tested function.

ideal-project-playbook

One branch, one merged pull request per iteration

Each iteration is a branch from the current main, a pull request whose body says what and why and shows the evidence, and a squash merge with a conventional title. History reads as the story of the work, and nothing depends on a conversation.

ideal-project-playbook

Check the property, not the symptom

A compile, a green build or a passing test is not the check that a change did what you meant. Check the property itself: that no string literal changed under a rename, that the output is byte-identical, that the real program says what you think it says. Almost every surprise in this project was a symptom taken for the property.

ideal-project-playbook

The levers that paid

A prebuilt tool instead of compiling it; a timeout on every job; the cache saved only from main; narrower triggers so a documents-only change skips the heavy jobs; no incremental builds or full debug info in CI; retries on the network. A policy swap (here, the audit's rules) was proven locally against a known-bad case before it replaced the old one.

ideal-project-playbook

Decide, following the canon and the project's interest

An agent given a principle decides, and says what it decided and why, instead of handing the choice back. It asks only when the answer needs something it cannot know, and it checks between iterations that each action still serves the purpose and is not busy work.

ideal-project-playbook

Documents are checked against the code

A document that names a path is checked to name a real one; a code example in a document is compared with the source; a page about how close the code is to the ideal says where it is not close. A guess written as fact is corrected in writing when it turns out wrong, and so is an invented date.

ideal-project-playbook

A fast local gate; CI for the rest

One command runs what must pass before shipping (format, lint, docs, links, licences, tests), writes each step's log to a file and prints one line per step. CI runs the heavy matrix. The gate is for reproducing a failure and for catching mistakes early, not a substitute for the pull request.

ideal-project-playbook

Findability as a test

Generate an outline from every module's first sentence, then ask it real questions in a test ("where is it said which kind of disk we work with?") and fail if the answer is not near the top. A cold read, turned into something that runs on every change. If a description is vague, or a thing is in the wrong place, it shows here first.

ideal-project-playbook

Generalise a tool with a parity test

When a script built for one project is made general, run the general one and the original on the original's own project and compare the results. If they differ, form a hypothesis and test it with a controlled experiment (give the new one the old one's exact rule and see whether the results then match) until every difference is explained and deliberate. A generalisation that is 'about the same' has changed something nobody chose.

ideal-project-playbook

Pin the real output

Record the exact text of the program's commands on a real fixture, and fail CI when it differs. A change to wording then shows as the few lines that moved, reviewed as such. Re-record only after reading the diff: a recording of empty output looks as clean as a good one until you read it.

ideal-project-playbook

Guards are tests that read the source

Architecture rules are ordinary tests that read the source tree (or its parsed form) and fail naming the file and line. A rule that lives only in a document is a wish; a rule that fails the build is a property of the project.

ideal-project-playbook

Look around first

Before acting, take a clear look at the situation: what is, what we are dealing with, why it is so, and what others already learned. Keep what was found as research - the question, the findings, their sources - so the decisions that rest on it can cite it, and anyone can follow a step down to what it stands on.

ideal-project-playbook

Look at what people will see

A check that a page answers, or that every link on it resolves, cannot see that it looks wrong. Look at it the way a reader will: a screenshot of the real page in a real browser, of the live site and not only of a local build. Three defects of this playbook's own site (literals not styled as code, a table of contents drawn like the navigation bar, headings drawn as links) were visible only that way.

ideal-project-playbook

Measure before you claim

Say how long, how many, how big, before and after, with the samples, and say when the samples overlap. A claim chosen from the best runs is not a measurement. When you find you overclaimed, retract it in writing, where the claim was made.

ideal-project-playbook

Measure the CI before optimising it

Collect wall time, job-minutes and the slowest jobs and steps over several runs, then change the critical path. The biggest win here was one step, a security audit that compiled its own tool for three minutes. Reject, with reasons, what the measurement does not support.

ideal-project-playbook

Names explain the program

Names of files, folders, actions and states say what the thing is for, in plain words. Folders are named for what the program is *for*, not for how it is built (`going_back/`, not `adapters/`). A part's first sentence says what it is for without a pattern word like adapter or port.

ideal-project-playbook

Judge CI by the newest run of each check

Reruns and flakes leave old failures in the history. Judge a commit by the newest run of each check name, count skipped as passing, and rerun a job the runner itself failed to start. A release is the commit titled as one, not the merge before it.

ideal-project-playbook

A fact, a word or a rule lives in one place

A sentence a person reads, a plural, a rule about disks, a way of counting: written once, in the layer that owns it, and used everywhere. Every copy is a place it can come out differently. Guards forbid the copy, and a helper makes the one place cheap to use.

ideal-project-playbook

Report in plain words, at the big picture

Say what changed, how much closer it is to the ideal, what went wrong, and what is next, in language a person who does not read the code can follow. Technical detail belongs in the log and the pull request. Own mistakes briefly and say what they taught.

ideal-project-playbook

Prove every guard bites

A guard that has only ever passed is unproven. Break the thing it guards on purpose, in a clean file, confirm it fails with a useful message, then restore the file *exactly* (and compare). Two checks can pass together for the wrong reason, for example a link and its target both wrong in the same way, so test the rule against the outside truth too.

ideal-project-playbook

Published identities are not renamed for a word

A key in a JSON output, a contract's identity, a stored word in a journal: other programs and older files read them. Give people a plain word beside the stored one, test both, and leave the stored one alone, with the reason written down.

ideal-project-playbook

Remove a race by construction

A rare failure is not disproved by many clean runs on a fast machine. Find the shared resource, put every use behind one lock, and show with a stress test that the original fails and the fixed version does not.

ideal-project-playbook

Debts are data and only shrink

A rule that cannot be met today is recorded as a number per file in a data file. The test fails if any number grows, and insists the file record any decrease. Progress cannot silently slip back, and what remains is a list anyone can read.

ideal-project-playbook

A stateless, resumable shipper

One script pushes, opens the pull request, waits for checks, merges and verifies. It keeps no state of its own, reading GitHub every time, and it stops itself before the tool's time limit with a code that means *run me again*. Any session can continue what another began.

ideal-project-playbook

Retire a word with a guard

When a word is wrong (here, *config* for an area), rename its uses with a lexer-based tool that follows string interpolation and verifies no literal changed, then add a guard that the word is not an identifier outside the adapter that owns it.

ideal-project-playbook

Say what to do next, once

Every situation where nothing is there, or something failed, says what to do about it, in the layer that owns the words, so every surface (command line, window) is equally helpful and none repeats it differently.

ideal-project-playbook

Search by shape, and read all of the results

To find a smell, search by its *shape* (every bare bool in a pair, every `if n == 1`), not by the instance you noticed. Read the whole result: a search cut off after ten lines once hid the one script that pinned a change, and CI found it.

ideal-project-playbook

Seeded cold reads

Pick modules at random with a seed (so the read is reproducible), read them as a stranger, and write down where you stumbled. It finds what no guard measures: a rule copied by hand, a stale word, a distinction the code makes and never names. It stops paying when a seed returns modules you have already read; that is the signal to read differently.

ideal-project-playbook

Each layer is a small language

A layer offers a vocabulary (types, verbs, nouns) and the layer above is written in it. A command reads as a story of those words: look, ask, begin, do, end, show. The reader meets the story first and the mechanism only when they ask.

ideal-project-playbook

State and plans live in the repository

An agent's memory is not the project's memory. The plan (backlog), the decisions (log), the rules (agent notes) and the documentation of the tools are files in the repository, so no session starts over and any agent can continue where another stopped.

ideal-project-playbook

The stranger test

Someone who has never seen the code should be able to say what a part is for from its first line, and be right. It is the measure of clarity, and the only one that cannot be gamed by moving code around.

ideal-project-playbook

Tools that rewrite code verify themselves

A splitter, a renamer or a formatter that edits many files checks its own work: every comment survives, no string literal changed, nothing is written unless everything matches. A regex rename once changed a JSON key and a fake tool's output; a lexer-based one that verifies the strings changed none.

ideal-project-playbook

Every layer is the top of the layers beneath it

Read from the top, each part says what it is *for*, in the words a person uses; each step down says *how*, using only the words of the layer beneath it. You can stop at any level and still understand the program, and you never have to hold all of it in your head. This is the one idea the rest of the playbook serves.

ideal-project-playbook

Two faces: what it is for, and a body in the words beneath

Every part has an upward face (its purpose, and the words it offers) and a downward face (a body written only in the words of the layers below). A part that cannot be described that way is doing two jobs, and is split.

ideal-project-playbook

Use the program as a newcomer would

Run the real program on a real disk, from first use to going back, and read every word it says; drive a terminal UI through a pseudo-terminal and print its screens. Reading code finds what is wrong with code; only using the program finds what is wrong with what it *says*.

ideal-project-playbook

Words are decisions

Choose each word as a decision: look at what others call the thing and what the reader already knows, prefer the plain word with one meaning, and keep the choice with the words rejected and the reasons. One language, used the same way in talk, in code and in documents.

ideal-project-playbook

A job is a record with a journal

A job's life is journalled - submitted, claimed with a lease, heartbeats, steps done, finished, parked - and the journal is the only truth; nothing is inferred from a missing file. Built 2026-11-12 in oco-agent/core: what may follow what in a job's journal is one function, so a finished, expired or parked job cannot be claimed - run once by construction.

lab-agent

A voice of its own

The agent's heartbeat is watched from outside the machine, and the client can raise an alarm without the agent.

lab-agent

Coordination for any driver

ocoeco is the memory and the language of the work; oco-agent is how work is coordinated: it takes work, does it, journals it, and talks with whoever drives it - people and machines alike, each through what suits them (a terminal interface for people, the phone, the command line for machines). It reads and writes ocoeco's shared tables instead of keeping a parallel set, and depends on ocoeco, never the reverse.

lab-agent

Jobs that do not conflict run side by side

A job declares the resources it holds - the phone, a repository, the build machine; jobs that share none run in parallel, so work goes on while a phone reboots or a kernel builds.

lab-agent

Resume, never replay

Work is a flow of idempotent steps, each journalled when done; after any interruption the flow resumes at its next step, and a finished job never starts again.

lab-agent

The driver's lease

Each driver holds a lease of its own, renewed by beats its client sends while it works; a job starts only while the driver who asked for it is still there. When a driver falls silent, its waiting work waits, others' work goes on, and what is running reaches its end.

lab-agent

Waits are measured where they happen

Every submit --wait and every wait records itself: what was waited on (a build, a reboot, CI, a harvest), for which project, how long. Gathered into each project's data like commits - made by the work, never typed.

lab-agent

Tables declared as data

Each repository declares its tables in a small readable file - fields, types, required, allowed values, patterns - and tad checks every row against it. The same declaration serves ocoeco's shared shapes, and others to come.

tad-engine

Three ways into the same data

A tad dataset is files you can read and diff, text you can reshape with jq and Miller, and a database you can query with SQL and joins - one dataset, with every change brought back to the same canonical files.

tad-engine

Additive-only file structure

Rhizoid-managed metadata (manifest, sync state) is added as new files alongside upstream's own, never edited in place inside upstream's existing files. This keeps a pull from upstream conflict-free for the tracked branch - not a guarantee that any patch to upstream code stays conflict-free, only that Rhizoid's own bookkeeping never collides with it.

git-rhizoid.github.io

Adopt an existing fork vs create a new one

Two different, deliberately separate operations: rhizoid add forks a new copy of upstream; rhizoid import points at a fork that already exists (with or without the rhizoid wrapper already on it) and adopts it into the manifest without creating anything. Kept as two verbs rather than one flag with a default, the way terraform keeps import separate from apply - the two operations have different blast radii and a wrong default in either direction is a real mistake (an unwanted duplicate fork, or silently overwriting someone's existing, satisfactory fork).

git-rhizoid.github.io

argenv declares flags and env vars - not subcommands or positionals

Read argenv's own source and README before designing against it: it is explicitly "a declared, typed contract for a program's invocation surface - argv and envp", and every Input it declares binds to a --flag/env-var pair, never a bare positional value. Confirmed by reading argenv-cli's own main.rs (the author's own reference CLI): subcommand dispatch is a plain match on args.first(), not anything argenv provides. Rhizoid's CLI follows the same shape: a thin hand-written dispatcher picks the verb and reads each command's one primary positional (a repo spec, a URL, a module name) directly; argenv declares only the named flags for each verb.

git-rhizoid.github.io

Auth: shell out to gh, for now

Rhizoid calls the GitHub CLI (gh) for anything needing authentication - forking, merge-upstream, reading repo state - rather than managing its own token or OAuth flow. Whoever already has gh authenticated can use Rhizoid immediately; the tool has no credentials of its own to store, rotate, or leak. Revisit if a use case needs something gh cannot do (a non-GitHub git host, for one).

git-rhizoid.github.io

Clean patch back upstream

Because Rhizoid's own metadata never touches upstream's files, a diff of the patch branch against the pristine tracking branch is a clean patch, submittable as a normal PR to the original repo, whether or not its owner has ever heard of Rhizoid.

git-rhizoid.github.io

No central lockfile - state is distributed into each fork

Cargo, npm, Poetry and Nix all pair a human-edited manifest with a separate, machine-written lockfile recording exact resolved state. Rhizoid does not need a top-level lockfile: each managed fork is already a real git repository with its own history, and its own .rhizoid/module.toml already carries that module's exact recorded state (see [module-metadata-file](concepts.md#module-metadata-file)). A central lockfile would just be a second, independently-driftable copy of information git already holds per-repo.

git-rhizoid.github.io

Status detects drift, not just reports the manifest

rhizoid status inspects the real state of every managed fork (does it exist, what commit is the tracking branch actually at, is there uncommitted or unmanifested structure) and diffs that against the manifest's record, the way terraform plan diffs real infrastructure against Terraform state. The manifest is a record of intent, not a source of truth Rhizoid trusts blindly - reality always wins the comparison.

git-rhizoid.github.io

Fork destination is a manifest setting, not hardcoded

Where a new fork lands (which org or account) is configured per manifest, with a default and a per-module override - the same shape as west's remotes list (a named set of url-bases) plus each project's optional remote: override. Nothing about Rhizoid assumes forks live in one specific org.

git-rhizoid.github.io

The manifest is TOML, with the footgun that argues against it named up front

TOML: native comments (unlike JSON), no implicit type coercion or indentation sensitivity (unlike YAML - see [the YAML document from hell](sources.md#yaml-document-from-hell)), and its array-of-tables syntax is a direct fit for "a list of modules, each a flat record". Cross-ecosystem adoption for exactly this kind of file (a hand-editable project/tool manifest, not a deeply-nested orchestration config) is real and independent of any one language: Cargo.toml, pyproject.toml, Hugo, Netlify. The honest counter-case: Cloudflare's Wrangler shipped TOML-only for years, then added JSONC and now recommends it for new projects, naming TOML's array-of-tables syntax as a real footgun in practice - a misplaced or missing [[table]] header silently puts a value in the wrong entry (see [the future of Wrangler configuration](sources.md#wrangler-toml-to-jsonc)). That risk is highest when a file is mostly hand-typed from scratch, which is not the common case here: the manifest is meant to be edited through add/import/remove, not freehand, and each module's own detailed state lives in its own .rhizoid/module.toml rather than piling many [[module]] entries into one large hand-edited file - closer to Cargo.toml's [dependencies] table (mostly tool-written) than to a large hand-maintained Wrangler config.

git-rhizoid.github.io

Each fork carries its own .rhizoid/module.toml

The additive metadata that makes a fork "attached" lives in a new .rhizoid/module.toml file at the fork's own root: origin URL, tracked ref, pinned commit, whether it was added or imported, when. Mirrors .tad/.gitrepo's pattern from the tad system - a plain, readable file is the source of truth for state, not something buried in commit messages or a separate database.

git-rhizoid.github.io

The v1 command surface: init, add, import, update, status, refresh, remove

init sets up a manifest. add forks a new module into the configured org and starts tracking it. import adopts an existing fork without creating one. update pulls upstream into a module's tracking branch (GitHub's merge-upstream). status reports drift between the manifest and real git/GitHub state. refresh reconciles the manifest to match observed reality without changing anything (mirrors terraform apply -refresh-only) - this is how a by-hand change gets folded back in rather than flagged as drift forever. remove drops a module from the manifest. send-upstream (clean patch back to the true upstream) is real but deferred to v0.2, after the core loop is proven.

git-rhizoid.github.io

Two crates: rhizoid-core and rhizoid-cli

Mirrors argenv's own workspace shape (crates/argenv + crates/argenv-cli). rhizoid-core holds the Manifest and Module types, their JSON Schema (via schemars, the same crate argenv itself already uses for its own contract feature), and the GitPort/GitHubPort traits the real fork/sync logic will implement later. rhizoid-cli holds argv dispatch and the per-command argenv Models. Splitting now, before there is much code, avoids a disruptive later refactor once the planned TUI needs to depend on the same core logic without the CLI.

git-rhizoid.github.io

Rhizoid-cutting (rhizcut)

A single dependency managed by Rhizoid: a real GitHub fork of an upstream repo, owned and pinned rather than referenced remotely. Named after a horticultural cutting - a piece taken from a parent plant and rooted separately, genetically identical at the start but independent from then on.

git-rhizoid.github.io

Tracking branch vs patch branch

The branch that mirrors upstream is never hand-edited - only fast-forwarded via merge-upstream. All customization lives on a separate branch that merges from the tracking branch. The tracking branch never conflicts; the patch branch might, exactly once, when upstream touches a line you also patched - that is inherent to patching, not a tooling failure.

git-rhizoid.github.io

The about link

Every record table names what it is about in one field, about, checked by a references rule against the base's subjects (its components, features, practices - and its own backlog). A word before a dash names a family: modem names modem-data, modem-calls and modem-sms.

ideal-knowledge-base

Briefs first, the whole on demand

Every record has a brief, its one line of at most 200 characters - a decision and a research a brief field, the rest their title - and a file opens with its own brief, its first paragraph. Every answer gives records by their briefs; an agent reads deeper - row --id, --whole true, a file past its first paragraph - only when its task needs more. A summary is the brief of a subject, as a brief is of a record.

ideal-knowledge-base

A row or a file

A thing there are many of with one shape - that is cited, linked, dated or changes state - is a row: a decision, research, a source, an item of work, a log entry, a concept, a test, a status, a word. Prose read once in order is a file: README, AGENTS.md, a brief, an essay too long for a row (kept in research/ and cited by a row). Rendered pages are output for people and the face, never what an agent reads to answer. The named statements are the base's interface.

ideal-knowledge-base

Followed by a pinned release

A base follows ideal-knowledge-base by a release named in its idealkb.toml, as it pins tad in bin/install-tad.sh. The generic files - the named statements, and AGENTS.md's and tables.toml's part between idealkb:begin and idealkb:end - are laid by bin/follow.sh; a weekly job on the lab machine moves the pin and lands through the base's own CI. A file the base keeps as its own is named in own.

ideal-knowledge-base

Five questions, one query each

Every base answers the same five questions the same way: about SUBJECT (everything known of it), next (the work ahead), find TEXT (ids and briefs of every record that says it), row ID (one record whole) and recent (what was recorded lately). tad statements lists everything else. Writing goes through named records - decision, research, backlog, session-log, source - each with --about.

ideal-knowledge-base

ikb: record by domain command

One command, ikb, gives each base's records as subcommands read from its records/*.sql at run time, so an agent needs only its man page (IKB.md) to add rows and files.

ideal-knowledge-base

One short entry

AGENTS.md is the one entry, under 3 KB, and CLAUDE.md is @AGENTS.md: what the base is in two lines, an orientation table from a typical question to the command that answers it, tad statements for everything else, and the rule: never read data/ or docs/ to answer - ask a query. Editing recipes belong in CONTRIBUTING.md.

ideal-knowledge-base

Research kept aside

A research is a row - the question, the finding, its sources, its date - and its own material, if any, is a dated folder the row names, research/SUBJECT/YYYY-MM-DD/. Redone research is a new row that supersedes the old; the old stays reachable but leaves the subject's answer.

ideal-knowledge-base

A base's change is a signal

When a base changed a generic file, the weekly job still lays idealkb's version, says so, and does not land: its pull request shows the base's change as a diff - the signal to send it upstream to ideal-knowledge-base, or to name the file as the base's own.

ideal-knowledge-base

The standing tables

Every base keeps backlog, session_log, decisions (with what was rejected), research and sources, each with about. A base adds its own subject tables beside them.

ideal-knowledge-base

A summary over many records

When one subject gathers records, its answer leads with a short, dated how-it-stands that condenses them; the records stay beneath, reached by id. The query says when one is due, by what the records weigh, and the session that records into the subject renews it.

ideal-knowledge-base

As good as Android

A phone running Linux that an ordinary person could use as their only phone and not feel they gave something up - counted one feature at a time.

docs

Mainline first, everything upstream

Work is done on mainline Linux and written to be sent upstream: each fix its own series, checkpatch-clean, to the upstream it belongs to; vendor code is read as a specification, never copied.

docs

Measured, not claimed

A feature counts only when a test run has shown it works; what nobody measured is unknown, never broken.

docs

No manual steps outside tools

What a person does twice becomes a command, a record or a test, so that bringing a phone up can run by itself; where hands or eyes are the measurement, the step is a witnessed test, said before and recorded.

docs

Rust, with argenv

linux-phone's tools are Rust, each declaring its command line and environment once with argenv.

docs

One baseline per device

Every check that ever passed is held to; a check outside a run's scope is not asked, rather than kept in a second baseline.

lab-tools

The conveyor refuses what cannot work

Each mistake that cost a try becomes a refusal with a reason: a kernel that is not an EFI program, a listening test without the word that the microphone is placed.

lab-tools

Read the device's own record first

Before cleaning up after an experiment, read what the device itself recorded: a boot entry's try counter, the bootloader's selection, the crash memory.

surya-lab

A placed microphone gives relative levels

A microphone placed by the phone tells which speaker is louder from where it stands, and whether there is sound at all - not absolute loudness.

surya-lab

The phone is the reference

Kept in a known-working state at all times: every experiment is one try that falls back by itself, and the phone is checked well before and after.

surya-lab

Glimpses, then changes, then releases

Work is recorded where it is fresh, as glimpses - at any moment, through ocoeco, not only when committing: research, prose, essence, code. A change (what lands) is the glimpses it carries; a release is the changes it ships. Git operations depend on ocoeco; ocoeco does not depend on git.

ocoeco

A program knows what it does

A test need not be a dead end beside a program: what a program does, looks like and how it meets others can be part of how it works - so it can say what is actually happening and how well, in words another program can use, and mend itself by a countermeasure that is declared and seen. Begun here without the name: ocoeco check brings every lens into focus; a write that would add a link to nowhere is refused, with why; oco-agent's pulse says it is well; the fulldome's screen is read back by a terminal emulator. Since 2026-11-12 a projection looks at itself before it reaches a surface (decision 2026-11-12-the-projection): the first place this is how the program works, not a test beside it.

ocoeco

Chainability

One project's data can feed another's - device tests into a grand project's path, a tool's releases into a lab's - each row carrying where it came from.

ocoeco

Data made by work

A project's data is produced by its work - commits, builds, tests, releases - not typed up afterwards; what only a person can supply is written once, where the work happens.

ocoeco

Manual-work saturation

A project's ledger of small actions done by hand, each counted. Doing one again bumps its count; past three it is saturated and asks for a tool. A record automated by a tool says so - and a later bump asks why it was done by hand again. Deliberate hand-work (looking, listening, deciding) is counted but never asks. Saturation is effort, not only count: minutes weighted by load (0-10, Borg CR10).

ocoeco

Lenses are additive

ocoeco is a rhizoid: anyone can write a lens, keep it to themselves or offer it upstream, and still pull updates - because a changed lens is a new lens, never an old one rewritten. A lens may add tables or fields but never changes what an existing one means, and it says which lens it grew from, so many near kin stay a family one can choose within rather than a pile.

ocoeco

Data made by work

A project's data is produced by its development and its functioning - commits, builds, tests, releases, measurements - as a principle and by tools, never kept by hand.

ocoeco

The observatory is a mirror

Projects produce their data; the observatory reads it. Everything breathes through ocoeco - its language, gatherers and checks - and no project needs the observatory to work.

ocoeco

One language, so the pieces join

Plain text tables, a mark, shared names for the common things (idea, path, workings, work), and data that feeds other projects' data with its origin on every line.

ocoeco

Prior art travels with the ideas

A project's sources are what people already learned that it stands on, and what it takes from each; concepts and decisions cite them, so the research behind an idea is seen where the idea is.

ocoeco

Look around first

Before acting: what is, what we are dealing with, why it is so, and what others already learned - kept as research (the question, what was found, its sources), cited by the decisions that rest on it, shown beside the steps those decisions are about.

ocoeco

Research has versions

A refresh adds a new version and never overwrites; earlier versions stay one click away. Views of facts follow the latest version; a decision keeps citing the version it rested on, and says when a newer one exists.

ocoeco

tad, the format

Text as data - tables as JSON lines with a schema, a canonical form and verification - is the format ocoeco speaks.

ocoeco

The same at every scale

Places nest by gathering - a star produces, a constellation gathers stars, an observatory gathers constellations and observatories - and lenses nest by composing, the fulldome being the outermost. So one act (observe) and one way of seeing (a lens) serve every scale, and nothing special is needed at the top.

ocoeco

Three ways of knowing

Live: gathered from a marked project as its work happens - the default, unmarked. Researched: taken from outside the commons, dated, with how it was found and its sources - shown outlined, with its age, linking to the research. Unknown: neither, and said so.

ocoeco

A vocabulary every project speaks

Each project keeps its words and their exact meaning - what a word means in plain language, what it is not, what it is easily confused with. ocoeco defines the shared words (mark, lens, essence, working, cutting, conveyor...); projects inherit them and add their own; a redefined shared word is flagged. Shown as a page, and as the terms underlined in the project's own pages with their meaning beside them.

ocoeco

Attention: where the whole is weakest

One view across every project, computed from their data: steps nothing delivers, work in progress that has not moved, regressions, and what waits on a person (a merge, a SIM card). Read at the end of every stretch to choose the next.

open-commons-observatory.github.io

The board

A project's live work - ongoing, waiting, planned - kept as data and shown in the picture next to its path.

open-commons-observatory.github.io

The conveyor

A forkable lab that holds everything a person or an agent needs to bring a goal about - for phones: tools, procedures, safety rules, principles; projects made from it carry the mark.

open-commons-observatory.github.io

Discovery, hexagonal

Finding projects is a port; each platform is an outlet - GitHub first, others (GitLab, Open Hub) later without touching the core.

open-commons-observatory.github.io

Essence

Both a method and the observatory's signature view. The method (its own project, creation-guidelines/essence-oco): how to say why and how of anything, as four answers each leading to the next - why it exists, what it must reach, how each step is delivered and proven, what is happening now - with the test of a good answer for each; it describes itself with nothing but itself. The view: a project's landing page, the chain down one line, with four marks for how completely it tells its essence.

open-commons-observatory.github.io

A grand project's family

The grand project's repository and every project whose parent is its owner or itself.

open-commons-observatory.github.io

Grand project

A marked project of kind picture: a large aim with its own tab, views and family of projects (Linux Phones is the first).

open-commons-observatory.github.io

The harvest

On a schedule, the observatory reads every marked project's shared tables, tags each row with its project and merges them; problems are shown, not lost.

open-commons-observatory.github.io

How we work, as a working set

Not a manifest but a usable set under one roof (the creation-guidelines organization): how to think - the canon's principles and architectures, the ideal project - and how to do - the practices, each naming the tool that carries it (land, shot, ocoeco check, lab-agent-oco) - shown as a lens like any other, and reachable by anyone through one command.

open-commons-observatory.github.io

Languages

Two kinds of text, each translated where it belongs: the interface in the face's Fluent catalogs (grammar and plural forms right), the data in each project's translations table (marked human or machine), falling back to the source. The site is the same static files per language under /<language>/, switched by a thin line of languages by their own names.

open-commons-observatory.github.io

Lens

A repository of its own (kind lens) that declares a family of projects and the views that show it - from a small shared vocabulary (path, matrix, families, runs, backlog, log, ideas, heartbeat, cards). The observatory discovers lenses and renders each with the same engine; curated lenses take its navigation, every other is listed among the discovered.

open-commons-observatory.github.io

The mark

oco.toml at a repository's root plus the oco-project topic (and oco-kind-<kind>): which project it is, its kind, its parent, the tables it shares.

open-commons-observatory.github.io

Milestone

A stop on a project's path, on one horizon, with criteria tied to measured data (feature statuses, tests, health); it fills by itself as evidence arrives, never by hand.

open-commons-observatory.github.io

The observatory

A meta structure, tied to no project: one living picture of every project of the open commons, built from the projects' own data.

open-commons-observatory.github.io

The observer

Half-manual tests ask an observer - a person today, a rig of cameras and servos later - with nothing else changing.

open-commons-observatory.github.io

ocoeco

The observatory's information ecosystem and its backbone - both a principle (data is produced by projects as they are made and as they work, never by hand) and a tool (formats and protocols, gatherers, chaining, propagation), in the repository ocoeco.

open-commons-observatory.github.io

The path

A project's visit card: a line through its three horizons, its milestones as stops, filled to where the evidence shows - and unknown shown as unknown.

open-commons-observatory.github.io

The readiness ladder

Under the horizons, a project's maturity on the established Technology Readiness Levels (concept to proven in operation), so projects of any kind compare on one scale.

open-commons-observatory.github.io

Shared parts as rhizcuts

tad, the mark and the conveyor's tools travel as rhizoid modules: owned, patchable git forks rather than template copies or subtrees.

open-commons-observatory.github.io

tad, the heart

tad - text as data - is the living heart and blood of oco-eco: the formats every project's data is kept in, the gatherers that fill them, the views that show them; supplied in every repository as a rhizcut.

open-commons-observatory.github.io

Text as data (tad)

Everything a project knows - plans, decisions, concepts, progress, measurements - is kept as tad data in its own repository, and rendered from there.

open-commons-observatory.github.io

Three horizons

Every project is measured against three: working (it does its job end to end), perfection (complete and polished - as good as it should be), ongoing perfection (it stays so: healthy, free of regressions, upstreamed, maintained).

open-commons-observatory.github.io

Unknown is not failure

What has not been measured is shown as not known yet - never counted as missing or broken.

open-commons-observatory.github.io

Replace a guess with a calculation

Which version is this, what does it need, does it need rebuilding, do these conflict, what may it touch, who is affected by this flaw, are these two things the same: each is guessed today and becomes a calculation once things have stable identities.

rhizome

The three mistakes, and the one beneath

Things are identified by name; versions describe whole components; boundaries are treated as walls - and beneath all three, isolation is the default and connection is work. All inherited from tape drives that read one file at a time, never designed.

rhizome

Identity by what a thing is

A definition is identified by a fingerprint computed from its own contents plus the fingerprints of everything it depends on (a Merkle tree; mutually dependent groups are fingerprinted together). Names become labels pointing at fingerprints.

rhizome

Structure, not text

The fingerprint is computed from the structure of the code - formatting, spacing and the names of internal variables fall away (alpha-equivalence). Two people making the same change in different styles produce the same fingerprint.

rhizome

The graph is the source of truth

What is stored, hashed, compared and edited is resolved structure. Text appears once on the way in and once on the way out, at one marked boundary; nowhere between is text anything but a derived rendering.

rhizome

There are no files

With every reference a fingerprint, imports have no job, and then files have none: there is a graph of definitions and links, looked at through views - slices you choose and switch between, typing ordinary code, navigating relationships instead of folders. Your layout is remembered as yours; authors may suggest a reading order.

rhizome

The closure

Start from what you want, follow every reference, stop when nothing new appears: exactly what is needed, nothing more.

rhizome

Grafting

Taking a piece of someone else's software into yours: its closure arrives, attaches, and remembers where it came from so improvements can go home. Wrap what exists, replace it gradually underneath.

rhizome

Changing is not editing

A changed thing is a different thing with a different fingerprint; the original stands and its users are unaffected. The chain above re-points with small records - 'same as before, except this reference' - bounded by your project. A succession link notes lineage.

rhizome

Frozen, with a path to fixes

Nothing updates unless you say so - which also means nothing is silently fixed. So: who is affected is a lookup; a fix arrives classified (drop-in, needs conversion, needs a rebuild); and per item you pin, follow, or defer to someone you trust. When two you trust disagree, you are shown both.

rhizome

Layers that can only add

Architectures, bindings, shims, features: each an additive piece with a condition on it, inert unless the condition holds - never fetched, never built, structurally unable to break anyone it does not apply to.

rhizome

No configuration files

Arguments, environment variables, configuration files and build flags exist because the finished program is a sealed box. A value is another item in the graph; configuring is pointing a reference elsewhere. Authors mark intended settings as exposed; some values genuinely arrive only at runtime.

rhizome

Secrets as handles

Secrets are never in the graph (nothing can be deleted from it, and fingerprints of short values can be reversed). The graph holds a handle resolved outside it when the program runs.

rhizome

Folklore becomes evidence

A measurement attaches to the exact value it concerns, with its conditions - this hardware, this workload, this result - and because the configuration is exact, anyone who doubts it can reproduce it.

rhizome

Stop searching the internet for your own computer

Every exposed value carries its names, its author's default, its explanation in place, its lineage, what it affects and what others measured; search narrows to what you are actually running, and alternative names anyone adds become search terms.

rhizome

The program is a receipt

The graph is the valuable thing; the program is a consequence recomputed from it, a cache entry nothing refers to. Understanding code is done once for everyone; preparing it for a machine is the cheaper half; only what actually changed rebuilds; results are stored by fingerprint too, so values sit beside the code.

rhizome

Everything visible, almost nothing present

The machine appears to hold the entire tree of all software; a thing arrives the instant it is needed - done at the filesystem so every existing tool works unchanged.

rhizome

One kitchen, many dishes

A long-running process keeps the shared groundwork warm; each program starts as a copy-on-write copy of it, in its own memory space.

rhizome

Absent, not forbidden

The list of pieces that built a program is its entire visible world: what it does not need is not denied to it - it is not there.

rhizome

Changing things while they run

Calls go through an index of where each thing lives; replacing a thing is updating its entry. Whether a change can go live is computed beforehand: inside of a function - swap; shape of stored data - convert first; a boundary - restart.

rhizome

Rigor as a dial

The same definitions expressed loosely - copying freely, vague errors, like a scripting language - or tightly - explicit ownership, no copying, precise types - tightened where a real wall is met; and tightening done once lives on the definition for everyone.

rhizome

Conjuring a shoot

You do not install software: you point at the rhizome, draw a boundary, and a working shoot materialises. The shoot and its names are yours and die with the conjuring; only the changed substance goes home.

rhizome

It behaves like a living system

Fingerprints are the genes and names the appearance; the Weismann barrier - the shape you drew and the name you gave stay yours, only substance is inherited; grafting is lateral gene transfer; renaming is a silent mutation; settings are gene regulation; disuse is how things die.

rhizome

Assembly, not invention

Every layer runs in production somewhere: structural identity (Unison), whole-tree-visible stores (Google, Microsoft, Meta), reversible slicing (josh), optional parts that stay unbuilt (the Linux kernel), fine-grained change analysis and edition morphing (Rust), the zygote model (Android), live patching (Linux).

rhizome

The first user ahead on day one

The risk is not the engineering but adoption: the first person to use it must come out ahead at once, alone, with no community behind them.

rhizome

Hypha

The first milestone: the content-addressed core. It reads real Rust, fingerprints every definition by structure and dependencies, keeps them in one shared graph per machine, and turns a chosen piece back into running code (graft).

rhizome