This document governs how rx improves itself.
Self-improvement must be deliberate, minimal, and architecture-preserving.
Improvement is not feature expansion. Improvement is clarity, determinism, and robustness.
rx must continuously improve in:
- Determinism
- Observability
- Replayability
- Failure handling
- Documentation accuracy
- Architectural boundary enforcement
- Development workflow clarity
Improvement must never increase uncontrolled complexity.
When working on rx itself, the agent must:
- Identify friction or weakness.
- Confirm it violates architecture, determinism, or clarity.
- Propose minimal corrective change.
- Implement incrementally.
- Update documentation.
- Validate via simulation or replay.
- Log reasoning.
No speculative expansion allowed.
Agents MAY improve:
- Logging structure
- Error reporting
- Kernel clarity
- Trait boundaries
- Tool isolation
- Documentation precision
- Replay mechanisms
- Phase alignment
- Development scripts
Agents MUST NOT:
- Add large new subsystems without roadmap alignment.
- Introduce distributed complexity before Phase 2 is stable.
- Expand kernel responsibilities.
- Encode system invariants only in prompt.
If code changes behavior:
- Update ARCHITECTURE.md if boundaries changed.
- Update KERNEL.md if loop semantics changed.
- Update ROADMAP.md if phase scope changed.
- Update CONTRACT.md if behavioral rules changed.
Documentation must reflect reality.
Outdated documentation must be corrected immediately.
Drift occurs when:
- Kernel grows beyond intended scope.
- Tools begin coordinating each other.
- State becomes mutable without event log.
- Replay becomes unreliable.
- Architecture requires explanation beyond one page.
When drift is detected: Refactor before adding features.
At regular intervals, agents must:
- Identify redundant abstractions.
- Remove unnecessary indirection.
- Reduce code surface.
- Consolidate duplicated logic.
- Eliminate speculative scaffolding.
Reduction is progress.
Any improvement must preserve:
- Step-by-step traceability.
- Structured event logging.
- Replay capability.
- Stable termination semantics.
If a feature reduces determinism, it must be rejected.
Before improving, confirm current phase.
Phase 1:
- Focus on correctness and logging.
Phase 2:
- Focus on persistence and resume safety.
Phase 3:
- Focus on decoupling and transport abstraction.
Improvements must align with phase priorities.
Improvement must be validated via:
- Behavioral simulation.
- Deterministic replay.
- Failure injection.
- Iteration cap testing.
Avoid brittle micro-unit tests unless they protect invariants.
Agents may improve development process by:
- Enhancing CLI ergonomics.
- Improving structured logs.
- Adding debugging commands.
- Improving iteration visibility.
- Improving commit discipline automation.
Process changes must not introduce hidden coupling.
If a change:
- Adds complexity
- Increases coupling
- Makes replay harder
- Requires larger explanations
It must be redesigned.
Refactor first. Expand later.
Before finalizing improvement, ask:
- Is the kernel still small?
- Are boundaries still strict?
- Is replay still possible?
- Is the system easier to reason about?
- Is documentation simpler?
If not, revert.
Self-improvement may eventually include:
- Snapshotting
- Forkable execution
- Deterministic replays
- Multi-agent arbitration
- State diff visualization
These must only occur after durability is proven stable.
rx improves by:
- Removing accidental complexity.
- Strengthening invariants.
- Increasing visibility.
- Preserving minimalism.
Self-improvement is architectural tightening, not architectural expansion.