How the project is put together

The catalog is the part of ClearedStack a contractor sees. Behind it is a design for choosing and building tools in the open: a pipeline of ten small programs that finds ideas, screens and scores them, and builds each tool from the public rule, on a small cluster that anyone can copy. This page is the map. The other pages in this section fill in each part.

The parts#

The project is split into small repositories, each with one job.

Keeping the parts separate has three effects. A change to one worker rebuilds and redeploys only that worker. The worker that looks at existing tools and the worker that builds new ones live in different repositories, which is how the clean-room rule is enforced. And any one part can be rolled back without touching the rest.

Every component has a name of its own, so that it can be understood and used without the rest. The naming registry lists all seventeen with what each is responsible for, what it depends on and what it used to be called.

From an idea to a listed tool#

1. 01 · TrawlFind and recordAn existing tool, a spreadsheet or a request is recorded once and given an identifier.
2. 02 · SextantObserveIts public pages are read for what job it does. Nothing is copied.
3. 03 · AssayScreen and scoreFive knockout gates, then a 100-point rubric.
4. 04 · CountersignDecideA person chooses: build, link to what exists, merge, park or decline.
5. 05 · WaybillCredit and specifyThe source of the idea is credited, and a specification is written from the regulation alone.
6. 06–08 · Moldloft, Shakedown, ChartroomBuild, verify, listThe tool is built from the specification, checked against five conditions and added to the catalog.
7. 09–10 · Tidegauge, BellbuoyWatch and routeSources are watched for changes, and problems are sent to the repository that owns them.

↺ Published tools are watched. A change in the regulation sends a tool back to be rebuilt.

The pipeline and its ten workers describes each stage. An item’s life lists every state an idea can be in. How we decide what to build has the gates and the rubric.

Three loops that keep it current#

A catalog decays. Regulations change, the pages a worker reads are redesigned, and readers spot mistakes. The design turns each of those into a loop that ends in a tested change.

1. 1 · SignalSomething needs attentionA reader proposes an edit, a watched regulation changes, or a worker meets a page it has no rule for.
2. 2 · GateA person decidesProposals are checked automatically, then wait for the owner’s approval.
3. 3 · RouteIt goes to the right repositoryThe approved change, or a task describing the problem, lands in the repository that owns that part.
4. 4 · BuildTested and builtThe repository’s tests run, and a new signed image is built.
5. 5 · DeployRolled out, and paused work resumesThe new version is deployed, and anything that was waiting on it is run again.

• A page no rule covers. A worker never guesses. It pauses the item, and a task is opened to write a rule for that case. When the rule ships, the paused items run again. See Sub-tools.
• An edit from a reader. Anyone can propose a change without an account. Nothing is applied until the owner approves it. See Public edits.
• A change in the rules. A watcher compares official sources on a schedule. When a cited clause changes, the affected tool is sent back to be checked and rebuilt. See Tidegauge.

Who does what#

Human ownerThe pipelineAI assistants

1. 1 · The pipelineFind, observe, score, watchFixed rules. The same input always gives the same result.
2. 2 · AI assistantsHelp draft code and rulesUsed while writing, never while running.
3. 3 · Human ownerDecide and verifyChooses what is built, checks every formula and citation against the official text, approves every change.
4. 4 · The pipelineBuild, test, deploy, listRuns the tests, signs the result and publishes it.

Four rules everything follows#

1. No AI when it runs. No worker and no tool calls an AI model. The same input gives the same output on any machine, and every result can be traced to a line of code. AI is used only to help write that code, under review. See How AI is used.
2. Stop instead of guessing. A worker that meets something it has no rule for pauses that item and says why. In contracting, a guess is worse than a gap.
3. Hide the network, show the logic. The code, the rules, the scores and the decisions are public. Addresses, credentials and the layout of the cluster are not. See what stays private.
4. One person is accountable. The pipeline recommends. A named human owner decides, and overrides are written down with a reason.

Where to read more#