You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Lead the README with the atom thesis, in a plainer voice
The opening argued structural authority. That is a safety property, not the bet
this project is making, and it was argued in a register that read as
pretentious.
It now opens on atoms: a reusable unit with identity, typed signature, contract,
documentation, declared effects, and evidence, larger than a helper function and
smaller than a workflow, reading nothing outside its arguments. Atoms compose
into molecules, molecules into control flow, control flow into a program.
Correctness is named as the dimension being optimized, and cost as its
consequence: a verified atom is capital, and reusing it collapses eleven stages
into a single obligation, that it still passes the new run's cases derived from
the new contract.
The cheaper-model claim is written as the hypothesis it is, and the kill
criterion the plan attaches to reuse is stated up front rather than buried in
the limitations. Authority and the known/ambiguous/recommended split are kept as
the habits they are, in one paragraph.
Every specific claim was read out of docs/plan.md or internal/pipeline first.
Change-Log: CL-20260802-026
Dev-Log: DL-20260802-036
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
**[Quickstart](#quickstart) · [How it works](#how-it-works) · [What it will not do](#what-it-will-not-do) · [User guide](docs/using.md) · [Contributing](.github/CONTRIBUTING.md)**
15
+
**[The idea](#the-idea) · [Quickstart](#quickstart) · [How a run produces code](#how-a-run-produces-code) · [What it will not do](#what-it-will-not-do) · [User guide](docs/using.md) · [Contributing](.github/CONTRIBUTING.md)**
17
16
18
17
</div>
19
18
20
19
---
21
20
22
-
## The argument
23
-
24
-
Most coding agents ask permission with a sentence the model wrote. You approve
25
-
the sentence. Then something else runs.
26
-
27
-
CodeFlux asks with the **exact action identity**: the tool, its ordered
28
-
arguments, and its declared effects. Approving `curl https://example.com` does
29
-
not approve `curl https://elsewhere`, and it does not approve the same URL
30
-
reached through a different tool. A denial is recorded against the *capability*,
31
-
not against the one tool you happened to be shown — so a refused action is not
32
-
quietly retried through a side door.
33
-
34
-
This matters because repository content is untrusted input. A poisoned `README`
35
-
can absolutely persuade a model to *propose* something hostile. It cannot
36
-
persuade CodeFlux that the proposal is authorized, because authority is never
37
-
derived from anything a model or a file asserts. That is the whole design, and
38
-
everything below follows from it.
39
-
40
-
The second commitment is narrower and just as load-bearing: **CodeFlux reports
41
-
what it knows, what is ambiguous, and what it recommends as three separate
42
-
things.** A forecast is a range, never a promise. An unreported price stays
43
-
`unknown` and is never rendered as zero. A passing validation means the checks
44
-
that ran passed — not that the change is correct. The execution graph explains
45
-
what happened; it does not prove that what happened was right.
46
-
47
-
An agent that overstates its own evidence is worse than no agent, because you
48
-
stop reading the diff.
21
+
## The idea
22
+
23
+
Most coding agents write a program in one pass and then try to check it.
24
+
CodeFlux builds one from the bottom up, out of **atoms**.
25
+
26
+
An atom is a reusable unit with a stable identity, a typed signature, a
27
+
contract, documentation, declared effects, and the evidence that it works. It is
28
+
larger than a helper function and smaller than a workflow. An atom reads nothing
29
+
outside its arguments, so what it does is determined by what you pass it.
30
+
31
+
Atoms compose into **molecules**, molecules into control flow, control flow into
32
+
a program. Each layer states what it must guarantee, and each guarantee names
33
+
the pieces that discharge it.
34
+
35
+
**Correctness is the dimension being optimized.** Everything else is downstream
36
+
of it. Cost is the interesting consequence: a verified atom is project capital,
37
+
so the next task that needs it recalls it instead of rebuilding it. When an atom
38
+
is reused, the eleven stages that established it collapse into one obligation —
39
+
it must still pass the *new* run's tests, derived from the *new* contract. Reuse
40
+
without that re-verification would just inherit the old blind spot.
41
+
42
+
That is also where the cost theory lives. If a program can be assembled from
43
+
atoms that are already verified, assembly is a smaller job than authorship, and
44
+
a cheaper model may be able to do it. Whether that holds is not settled.
45
+
46
+
**This is a bet, and it is written down as one.** Two of them, really:
47
+
functional decomposition into pure atoms, and the claim that verified reuse
48
+
compounds. The plan gives atom reuse an explicit kill criterion — if it produces
49
+
no measurable improvement in defects, review time, or total cost, it goes. The
50
+
prototype exists to find out.
51
+
52
+
Two habits hold the rest together. Authority comes from what an action *is* —
53
+
the tool, its ordered arguments, its declared effects — not from what the model
54
+
says it needs, so a poisoned file can persuade a model to propose something but
55
+
cannot make it authorized. And what is known, what is ambiguous, and what is
56
+
recommended stay three separate things: a forecast is a range, an unreported
57
+
price stays `unknown` rather than becoming zero, and a passing check means those
58
+
checks passed and nothing more.
49
59
50
60
---
51
61
@@ -102,7 +112,20 @@ Delete that directory and CodeFlux is gone. Your repository is not part of it.
102
112
103
113
---
104
114
105
-
## What it actually does differently
115
+
## What it does differently
116
+
117
+
### Atoms are kept, and re-verified before they are reused
118
+
119
+
A verified atom carries its purpose, inputs, outputs, algorithm, and the
120
+
metadata a later run needs to find it. Documentation is written *after* the
121
+
tests, the fuzzing, and the mutation score, so it describes what the atom is
122
+
known to do rather than what its author meant.
123
+
124
+
A later task looking for the same contract recalls that atom instead of writing
125
+
a new one — but only if it still passes the tests the new run derived from the
126
+
new contract. An atom that fails re-verification is rebuilt. Molecules are
127
+
registered the same way, because a registry holding only leaf functions makes
128
+
every run rebuild the joins.
106
129
107
130
### It never edits your checkout
108
131
@@ -304,21 +327,20 @@ flowchart TD
304
327
class GATE1,GATE2,GATE3,GATE4 gate
305
328
```
306
329
307
-
Three things in that picture are load-bearing.
308
-
309
-
**Tests come before the thing they test, and cases come before the tests.**
310
-
Stage 7 derives a ladder of inputs from the *signature* — straightforward,
311
-
degenerate, edge, complex, wrong, pathological — before any test is written. A
312
-
test written by reading an implementation checks what the code does; a case
313
-
derived from the contract checks what the signature promised, and those two
314
-
differ exactly where the bug is.
315
-
316
-
**Ordering within a phase is an argument, not a convention.** Anti-pattern
317
-
detection sits *after* verification because a swallowed error is neither a
318
-
compile error nor a test failure — no test written against current behavior
319
-
would ever catch one. Optimization may only run *after* mutation scoring,
320
-
because rewriting code guarded by tests nobody has shown can detect a defect is
321
-
how a behavior change reaches delivery with a green suite behind it.
330
+
Three details in that picture matter more than the rest.
331
+
332
+
**Cases come before tests, and tests come before code.** Stage 7 derives a
333
+
ladder of inputs from the *signature* — straightforward, degenerate, edge,
334
+
complex, wrong, pathological — before any test is written. A test written by
335
+
reading an implementation checks what the code does; a case derived from the
336
+
contract checks what the signature promised. They differ where the bug is.
337
+
338
+
**The order within a phase is deliberate.** Anti-pattern detection runs *after*
339
+
verification, because a swallowed error is neither a compile error nor a test
340
+
failure and no test written against current behavior would catch one.
341
+
Optimization runs *after* mutation scoring, because rewriting code guarded by
342
+
tests that have never been shown to detect a defect is how a behavior change
343
+
ships with a green suite behind it.
322
344
Documentation comes *last*, after fuzzing and mutation, so it describes what the
323
345
atom is known to do rather than what its author meant.
0 commit comments