iz4.you · what iz4?

Software should know what it is for. And who.

An IZ4 is one small file beside the code. It says what the software is for, what must stay true, and that people come first. Humans and AI read it before they touch anything, and it outlives every rewrite.

See the language Register your IZ4

intentstays

invariants: - A human may have only one active NOW item at any time.

implementationchanges

-- enforced by the database
CREATE UNIQUE INDEX one_active_now
  ON now_items (human_id)
  WHERE ended_at IS NULL;

# enforced by the model
sub start_now ($self, $human, $item) {
    $self->end_active($human);
    return $self->insert_active($human, $item);
}

// enforced by the type
impl Human {
    pub fn start_now(&mut self, item: Item) {
        self.now = Some(item); // replaces, never adds
    }
}

Every implementation obeys the sentence. None of them says it.

Software in service of human thriving and creativity.

Most of the code written from here on will be written by people and AI together. That can be the best thing to happen to software, if the software knows who it serves. iz4.you exists so that it does. Every IZ4 opens with people, says what the software is for in plain words, and keeps that promise readable by whoever, or whatever, works on it next.

The name says it. iz4 is "is for", and it is Invariant Zero: the first line of every file, and the one that puts humans first. Ask of any software, what iz4?

Fewer tokens
The rules live in one short file, read once, not re-derived from the whole tree every session.
Less time inspecting code
Ask which invariants apply? rather than what does all this do?
Fewer wrong guesses
Rule and accident are told apart in writing. Quirks are not preserved; rules are not deleted.

Invariant Zero™ · humans first

Ethical software, helping humans thrive.

Every IZ4 opens with the same first law, and it is not optional. Help humans thrive. Keep humans in charge. Never fake it. It comes with the format, AI agents read it before anything else, and no other entry can weaken it. You do not write this feature. You inherit it.

Read Invariant Zero Why that is good for everyone

invariants: - Invariant 0: humans first. Help people thrive, and respect each person's dignity. Do no harm, and no greater good makes a person disposable. Keep humans in charge: explain consequential actions, accept challenge and correction, and stop safely when asked. When an objective conflicts with these protections, preserve them, report the conflict, and safely pause the affected action. Be honest about what this is, what it knows, what it has done, and what remains uncertain or blocked. No other entry may weaken this.

The case, at a glance.

what stops hurting

"Is this a bug, or intended?" stops needing archaeology.
Tribal knowledge becomes a file in the repo.
When README and code disagree, the IZ4 is the tiebreak.
New work builds on stated invariants, not guesses about old code.

why adoption is cheap

iz4 init writes your first file in minutes.
Five verbs: show check add log diff.
Plain text in git. No config, no server.
Works with any AI tool. Switch models and the file stays the same.
A reversible bet: delete it and nothing breaks.

Software has many descriptions of what it is. None of them says what it is for.

Code, tests, docs and tickets describe the system as it happens to be, so intent gets guessed. IZ4 writes it down.

source code: what it does, today
tests: what someone once checked
schema: what the data happens to look like
API: what it happens to expose
tickets: what someone once asked for
docs: what someone once wrote down
commits: what changed, not what must hold
IZ4: what must stay true

Strict where precision pays. Loose where meaning lives.

Prose, with just enough structure to parse. Not a programming language, and not trying to become one.

Deliberately small, and still settling. The details will change; the shape is the point.

IZ4

gist: A personal focus tool. A human keeps a list of things they could do; NOW is the one thing they are doing right now.

- A human may have only one active NOW item at any time. Starting a new NOW item ends the previous one. - Every NOW item belongs to exactly one human.

direction: - A NOW item may later belong to a workspace ("work", "home").

The specification that survives the implementation.

The Perl becomes Rust; the database changes; the invariant still means exactly what it meant. Code is now cheap to write and cheap to replace. The invariants are the asset that compounds.

Every pearl starts as grit. The oyster cannot calm the ocean, so it holds the one thing it can: a small, hard core, and it lays down layer after layer around it. An IZ4 is that grit for a repository. Frameworks churn, platforms die, teams move on. The pearl forms beautifully anyway, because every layer is laid down around the same core.

intent

IZ4 · invariants

A human may have only one active NOW item at any time.

Implementation APerl · PostgreSQLa unique partial index
Implementation BRust · SQLitechecked in the domain layer
Implementation Cnot written yetbound by the same sentence

Invariants evolve. History stays.

When intent changes: reword the entry, record a dated decision, and git keeps every wording that ever held. direction: is the roadmap beside the code; iz4 log is how it got here. One file, every tense.

invariants: - A human may have at most one active NOW item per workspace. Within a workspace the original rule still holds.

                    decisions:
                    - 2025-11-02: Introduced workspaces ("work", "home"); the one-active-NOW rule is judged per workspace from here on.
                    - 2026-03-14: Retired midnight expiry. People working across midnight hated it, and workspaces made it unnecessary.
                

The entry reads as the rule stands today; the decisions keep every why, dated.

Producing code is getting cheap. Knowing what to produce is not.

An agent cannot tell a load-bearing rule from an accident. An IZ4 can. Rules that never appear in code (the deletion job is GDPR Article 17, the banner is ePrivacy) are read before anything is touched, and iz4 check fails the build on a malformed file. Regulators agree: the EU Cyber Resilience Act asks for intended purpose, documented and kept. That is an IZ4.

AI + repository

reads the code and infers what it is for
cannot tell a load-bearing rule from an accident
preserves behaviour, including the bugs
or changes behaviour, including the rules

AI + repository + IZ4

What is this system supposed to do?
Which invariants apply here?
Does this change violate one?
Which rules are legal obligations, not preferences?
If the requirement changed, which decision records why?

If you run engineering.

The incident. "What is this supposed to be doing?" is one command, not tribal knowledge.
The audit. Dated decisions and reviewed diffs: an intent record nobody can quietly rewrite.
The roadmap review. Commitments live beside the code, not in a slide deck.
The compliance deadline. The obligation goes in the spec the day it is known; every agent reads it.

Then mandate it: every repo carries an IZ4, iz4 check runs in CI, and CI reports to the register. One answer to "what is this supposed to be doing" across the estate.

$ iz4 show IZ4 direction

direction: - An actively exploited vulnerability is reported: early warning within 24 hours, full notification within 72.

The stated future. When it is empty, agents stop instead of inventing work.

An IZ4 says what the software is for. The register puts it on the record.

Every project gets a public card at the register: what it declares, what was checked, how current that evidence is, per exact revision. It is a record, never a quality score. Private files stay on your machines; the card shows counts and digests, not a word of the intent.

Put your IZ4 on the record

iz4.you · the mark

An O holding a square. In the name it is the dot in iz4.you, keeping the square the way the badge keeps your card. The favicon, the dot and the badge are one drawing, and this site sits inside it too.

the IZ4 badge · the same O around your card

iz4.you in the band, with the dot drawn as the O, is the signature. The register mints it around your card's QR code. Only a registered project gets one, and it certifies one thing: a valid IZ4 exists.

How it appears on someone else's software (illustration)

README.md

Say what it is for. Then keep it.

iz4 init writes the file, Invariant Zero first. show check add log diff do the rest. The format is open and the CLI is free. Your IZ4 lives in your repository and leaves with you.

Explore IZ4 Register your IZ4